[FFmpeg-user] Some more thoughts on documentation
cpz at tuunq.com
Sun Aug 23 21:07:03 EEST 2020
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.
- is it correct? (anecdotal info suggests it isn't always, see other emails
- 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
- do they follow commonly-accepted rules for that format (i.e. "man page"
- 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
- 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
- because the text is too long- propose something shorter with at least the
- 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
More information about the ffmpeg-user