[FFmpeg-user] Some more thoughts on documentation

[Carl Zwanzig]

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!