Hello,
I'm fairly sure that someone will object to a point below. Go ahead, but
also suggest something better; if you can't think of an improvement, maybe
it's better not to say anything. (And if something is not correct, tell us
what is; just saying "Wrong!!" is not helpful.)
On 8/23/2020 12:15 AM, Gyan Doshi wrote:
Yes, there's only one source repository for the documentation text, and the
format is texinfo.
Original content:
- is it correct? (anecdotal info suggests it isn't always, see other emails
about docs)
- are pieces missing? (intentional or not) (e.g. IIRC the docs still do not
list the values set by -target, it should) A user shouldn't need to look at
the source code; if they do, it's a failure to document.
- are parts redundant? (it the same thing is covered in two different
places, that's probably one too many)
(If parts of the texinfo file(s) are created from other source code, we have
to go back to those files and check all that again. And also ask whether the
sourcefile->texinfo process is correct.)
Process to create output docs:
- does it really include/exclude the correct parts?
- does it always run without intervention and is resilient to input errors?
- does it gracefully handle process and input errors and report them?
Output organization & formats:
- are they appropriate & usable for the different audiences? (some like the
man pages, some like the -all pages, some want more segmentation and
cross-linking, etc)
- do they follow commonly-accepted rules for that format (i.e. "man page"
format)?
- is the some way to make them more usable?
The purpose of all of that is to (re)verify correctness, not to find fault
in someone else's work, and unless a point is actually verified and
checked-off, then it's still unknown. This is all basic QA stuff.
"Rules of the game"? Not rules but maybe guidelines. If someone objects to a
doc update...
- because the content is wrong- point to the code that doesn't match (just
saying "wrong!!" isn't helpful; nor is saying RTFS! unless it points to the
relevant code)
- because the text is too long- propose something shorter with at least the
same info
- because the language is awkward, suggest how to reword it
- because you just don't want it changed- explain why
Charlie's Rule of Technical Reading
It doesn't say what you think it says, nor what you remember it to have
said, nor what you were told that it says, and certainly not what you want
it to say, and if by chance you are its author, it doesn't say what you
intended it to say. Then what does it say? It says what it says. So if you
want to know what it says, stop trying to remember what it says, and don't
ask anyone else. Go back and read it, and pay attention as though you were
reading it for the first time.
--Charles E. Beck, P.E., Seattle, WA c2005
Later,
z!
_______________________________________________
ffmpeg-user mailing list
ffmpeg-user@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-user
To unsubscribe, visit link above, or email
ffmpeg-user-requ...@ffmpeg.org with subject "unsubscribe".
