[FFmpeg-user] "documented implicitly" [was: Re: Why is format=rgb24 required after maskedmerge?]

[Jim DeLaHunt]

On 2020-08-19 19:14, Mark Filipak wrote:

> On 08/19/2020 01:43 PM, Jim DeLaHunt wrote:
>> …
>> Wow, "documented implicitly". This is such a classic FFmpeg project 
>> statement. The role of documentation is to explain, explicitly, at a 
>> suitable level of detail. What does "documented implicitly" even mean?
>>
>> I think this thread points out is that FFmpeg documentation is 
>> inadequate. It is hard to prove a negative, but I suspect that the 
>> term "pixel format" is not actually defined in the FFmpeg 
>> documentation. I suspect that the statement, "Any filter can change 
>> pixel formats" is not stated either. Certainly the maskedmerge filter 
>> documentation[1] doesn't mention pixel formats at all, much less say 
>> what pixel formats the filter sets for its output.
>>
>> I have attempted to improve the documentation, to make it explain 
>> explicitly instead of fail to document. I encountered a great deal of 
>> resistance to those patches, because they make the documentation more 
>> explicit, because they have more words, and because documentation has 
>> so little value in this project relative to executable code.
>>
>> And yet "You are deeply confused about our filters". In other words, 
>> the documentation has failed to explain to you what FFmpeg does, the 
>> project has failed to write or welcome improved documentation, you do 
>> not understand how FFmpeg works — and somehow this is your fault.
>>
>> [1] http://ffmpeg.org/ffmpeg-all.html#maskedmerge
>
> I have a theory, Jim. I think the developers don't document things (or 
> comment their code) for 2 reasons: 1, They want to be able to change 
> methods and behaviors without having to maintain documentation, and 2, 
> They want to make money doing consulting jobs for people who commit 
> ffmpeg for their projects, then give up trying to write ffmpeg command 
> lines. 


Actually, I disagree with that. I have seen debates on the FFmpeg 
developers list which show concern for preserving methods and behaviours 
as experienced by other code. And I haven't seen evidence that getting 
more money from consulting jobs is why the FFmpeg developers are 
blocking documentation. If that were a motivation, I would expect to 
have seen FFmpeg developers offering paid support services on this list 
before now.

My own theory is that the FFmpeg developers have ended up in a culture 
where the only activity they value is modifications to executable code, 
and so documentation is of no value.  The needs of FFmpeg users who 
aren't deeply reading the FFmpeg source code don't seem to carry much 
weight in that culture.