[FFmpeg-user] Help in improving the documentation is always welcome? [was: write output of find_rect to a file?]

[Jim DeLaHunt]

On 2020-07-12 14:07, Carl Eugen Hoyos wrote:

> …The size of such a change [to the documentation] often gives a good 
> indication of its usefulness. 


That rule of thumb might apply in some cases, especially where the 
current documentation is so close to the peak of perfection that any 
step is more likely to be downhill than uphill. But it sure doesn't 
apply to the FFmpeg documentation today.

FFmpeg documentation is inadequate due to several causes, including:

 1. Only some was accurate, complete, and well-written to start with,
    while some was inaccurate, incomplete, and/or poorly-written when
    contributed.
 2. The executable code changes constantly, and the documentation
    sometimes (usually?) does not change to describe the changed code
    behaviour accurately, completely, in well-written prose.
 3. The structure of the documentation, which might have been adequate
    years ago for a simpler product with a smaller volume of
    documentation, does not improve to meet the needs of a larger, more
    complex volume of documentation.
 4. The project has few cultural or structural mechanisms for
    encouraging documentation contributions, no metrics for measuring
    the quality and adequacy of new or existing documentation, and a
    proven track record of rejecting documentation contributions not
    connected to code changes.

Thus, the project now ratchets downward in adequacy of documentation 
over time.

You know, Carl Eugen, you could have replied with "Better documentation 
is good. I wish we had more good documentation patches. I encourage 
people to make them. I will help to improve them and help get them 
committed. But not all changes are good." Instead you replied with just 
the snark. That is an example of #4, in my opinion.

But I do thank you for the help you give on this list. Best regards,
      —Jim DeLaHunt, software engineer, Vancouver, Canada