[FFmpeg-user] Some more thoughts on documentation

[Phil Rhodes]

    On Monday, 24 August 2020, 19:28:11 BST, Jim DeLaHunt <list+ffmpeg-user at jdlh.com> wrote:  
 > agree about the value of narrative descriptions.  For instance, in 
> reading the DirectShow "How to Play a File" article, I think of how very > helpful it would be to have a narrative description of "How FFmpeg calls > a video filter", which describes the entry points to a filter and when > FFmpeg calls them and what the filter is supposed to do in response. 
Yes, that sort of thing.
The first thing to do, I'd have said, was to look at the scope of the project. What you're talking about there is not so much documentation of ffmpeg, which I would take to mean the command line tool, but libav... er... wherever all the filter stuff is. Which is fine, but it's a different purpose and a different audience. A fully comprehensive documentation of all the AV libraries is a big job. I'm not sufficiently expert to comment on the specifics, really, but certainly the current advice at ffmpeg.org is simply to look at the doxygen stuff in the headers which is completely inadequate.
Talking about the command line tool is a separate, more user-facing thing. Not mutually exclusive, of course, but different.
I still worry about the whole idea, though. Notice that nobody from the ffmpeg project is now participating in this discussion. Documentation is not valued, people who are not software engineers are not valued. We might safely predict that they will find any way they can to reject what we're talking about here, to disassociate themselves from it, to minimise and ignore it. We've talked about the in-group, out-group stuff on this list a lot, it is endemic in open source software, and it is not great. I would want assurances that any work done on more complete documentation for ffmpeg would be taken seriously, and that any such initiative would receive reasonable support from software engineers where that was required. 
Even if they gave us that, I wouldn't trust them not to go back on their word a week later, and I think it would be practically impossible to maintain a good ongoing working relationship. Even software people who work on commercial projects generally have to be made to do this stuff by their bosses. When there is no boss, you get... well, the status quo ante.
P