Re: [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


___
ffmpeg-user mailing list
ffmpeg-user@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
ffmpeg-user-requ...@ffmpeg.org with subject "unsubscribe".

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

[Carl Eugen Hoyos]

Am So., 12. Juli 2020 um 22:14 Uhr schrieb Jim DeLaHunt
:
>
> On 2020-07-12 05:21, Moritz Barsnick wrote:
>
> > …(Help in improving the documentation is always welcome….

Useful help in improving the documentation is welcome.

The size of such a change often gives a good indication
of its usefulness.

Carl Eugen
___
ffmpeg-user mailing list
ffmpeg-user@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
ffmpeg-user-requ...@ffmpeg.org with subject "unsubscribe".

Re: [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 05:21, Moritz Barsnick wrote:

…(Help in improving the documentation is always welcome…. 



I wish it were so, Moritz. But in my experience, improving the 
documentation is not always welcome.


For example: 
 and 
thread.


And: 
 
and thread, and conflict, and actual vote to accept doc change.


And the absence of documentation improvement patches which are not part 
of new code on ffmpeg-devel for the last forever.


It's a pity, because I think that the FFmpeg documentation is 
inadequate, that the inadequacy creates obstacles for users, and as a 
result there is more support work to do on the ffmpeg-users mailing 
list. If help in improving the documentation were more welcome, then I 
think both the developers and the users of FFmpeg would have better 
experiences.


I realise it is not in your individual power to fix this, Moritz. 
However, I want to be sure you are realistic about the actual situation.


Thank you for your help on this list, and for all you do for FFmpeg. 
Best regards,

 —Jim DeLaHunt, software engineer, Vancouver, Canada


___
ffmpeg-user mailing list
ffmpeg-user@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-user

To unsubscribe, visit link above, or email
ffmpeg-user-requ...@ffmpeg.org with subject "unsubscribe".