[FFmpeg-user] "documented implicitly" part 2 [was: Re: Problem while converting DNG sequnece to video file]
list+ffmpeg-user at jdlh.com
Fri Aug 21 10:48:42 EEST 2020
On 2020-08-20 17:13, Phil Rhodes via ffmpeg-user wrote:
> 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."
More information about the ffmpeg-user