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

[Mark Filipak]

On 08/20/2020 02:59 AM, Paul B Mahol wrote:
> On 8/20/20, Mark Filipak <markfilipak.windows+ffmpeg at gmail.com> wrote:
>> On 08/19/2020 01:43 PM, Jim DeLaHunt wrote:
>>> On 2020-08-19 07:34, Paul B Mahol wrote:
>>>> You are deeply confused about our filters.
>>>> Any filter can change pixel formats to one that they accepts thus gbrp
>>>> is picked instead of packed rgb, this is already documented
>>>> implicitly.
>>>
>>> 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.
> 
> Your both theories are fully correct. They want to make money for living.

Of course. You all need to make a living. But is frustrating users, including potential clients, the 
way to do it? Before I retired, I ran quite a few projects in many companies. We never minded 
spending money. Meeting schedules and objectives were always more important than saving money by 
doing jobs in-house. What we wanted most was smooth project development with predictable costs and 
reliable results. Cooperative, forthcoming people are worth their weights in Gold and usually result 
in follow-on jobs and recommendations to others. But what's going on here just sours potential 
clients. How wants to hire a consultant who jerks people around?