[FFmpeg-user] Some more thoughts on documentation

[Mark Filipak]

On 08/23/2020 02:07 PM, Carl Zwanzig wrote:
-snip-
> 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

I like it!

I also like: "Don't tell, show!"

Lots of examples. Examples of increasing complexity that are selected to progressively illustrate a 
single principle without explicitly preaching.

Lots of pictures and diagrams.

Emphasis of scanability and hackability as much as on readability.

Only one idea per sentence, one subject per paragraph. Favor separate short sentences over compound 
sentences. Favor repeating names over using pronouns: "that", "this", "it", etc. If pronouns are 
used, employ references within the same sentence, not to previous sentences, not to future 
sentences, and certainly not to other paragraphs. Try hard to make the subject of a sentence a named 
item instead of a pronoun -- reserve pronouns for objects or object clauses.

Developer preparation: Kindly add comments to the source code. The comments don't need to teach or 
explain. They just need to repeat the code's logic, but in English instead of Martian.