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
_______________________________________________
ffmpeg-user mailing list
[email protected]
https://ffmpeg.org/mailman/listinfo/ffmpeg-user
To unsubscribe, visit link above, or email
[email protected] with subject "unsubscribe".
