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."
_______________________________________________ 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".
