[FFmpeg-user] "documented implicitly" part 2 [was: Re: Problem while converting DNG sequnece to video file]

[Jim DeLaHunt]

On 2020-08-20 17:13, Phil Rhodes via ffmpeg-user wrote:

>   People;
> This is not a new issue and I'm really rather tired of hearing it discussed.
> The open source software movement is notorious for creating an absolutely horrible user experience and one of the reasons that happens is because of poor or effectively nonexistent manuals.
> Most of the people involved seem to view the involvement of non-software-engineers as inappropriate, even though that massively reduces the value of the work they're doing.


I won't disagree with you about concerning this project. However, it is 
not true for all projects. The Python community is an example of a free 
software project that has done quite a good job with documentation, and 
with welcoming contributions beyond executable code. This project can do 
better if it chooses to.


> It's not that hard to solve. Speaking as someone who makes a reasonable amount of money out of technical writing, documenting software is the next best thing to busywork. It does not require a knowledge of software engineering. It may require consultation with software engineers.


Speaking as a software engineer who frequently writes as part of the 
craft of designing and applying software, and as someone who has worked 
with professional technical writers, I hear what you are saying.

To improve this project's documentation, yes, a lot of writing may turn 
out to be straightforward. However, this project will require special 
skills in a few ways: 1. extracting the information by reading the 
source code, because consultation with software engineers will be hard 
to come by; 2. designing the structure and tooling of improved 
documentation, because I think the current structure and tooling is not 
up to the task; and 3. dealing with all the cases in which the code 
doesn't do what the developers think it does, and the documenting the 
code's actual behaviour will bring this to light.


> The ffmpeg project will find a way to reject any offer of help with documentation; it has been repeatedly offered and turned down (for no good reason.)
> At some point you're not really negotiating with a human being, you're just being told off by someone's ego.
> We can't force them.


Maybe I have more optimism about this than you do. I believe a lot of 
the FFmpeg developers do read this list. We are holding a mirror up to 
the project, and inviting them to take a look. In due time I think 
project participants may see something they perhaps don't look at often. 
Maybe they will want to stop what you rightly describe as "massively 
[reducing] the value of the work they're doing."