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

Mark Filipak markfilipak.windows+ffmpeg at gmail.com
Thu Aug 20 22:44:48 EEST 2020

On 08/20/2020 12:03 PM, Alexander Strasser wrote:
> On 2020-08-19 22:14 -0400, Mark Filipak 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
> There are some good points mentioned above.
>> 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.
> This conclusion however is way to unbalanced.
> I will bring up a point that has become clear to me.
> Good documentation in general and especially for software is
> incredibly hard to write and get right!

No, it's not. Or rather, it shouldn't be.

> In general you have to be a good writer and have sufficient
> insight into the tech you are documenting. And this means for
> FFmpeg you need to understand C enough, so you can roughly
> read the code and are able to ask the right questions.

Coders should not write documentation. Coders should write comments in their code. Documentarians 
should write the documentation.

Software engineering teachers drum into their students the importance of top-down design for a 
reason. Anything else is just code hacking: The coder punches into a problem at the point where 
he/she knows the most or has the kernel of an idea, and then builds the code out from there. That's 
not good practice, but it's what's done all too often. Code hackers don't write documentation 
because they don't know where they're headed.

Top-down design begins with documentation: A description of the intended structures and processing. 
For the coders who worked for me, I wrote the initial documentation which they followed as they 
implemented the code.

For example, the comments in a routine that parses macroblocks shouldn't teach people about the care 
and feeding of macroblocks. It should simply make plain-language statements about what it does, what 
it looks for, what 'states' it enters/leaves, and why.

Coders don't need to be good writers. They just need to comment their code to detail the logic in 
plain language. Documentarians do need to be good writers, but they don't need to be coders (or, at 
least, they don't need to be coders in the target language -- though that does help). Most of all, 
they do need to be logicians. And they need to have access to the coders and they need to take the 
lead in design reviews. That assumes that there are design reviews, but that's often not the case in 
informal organizations like ffmpeg.

> You need to have enough multimedia knowledge and experience
> so you can try things yourself and write things in sufficiently
> understood language.

The documentarian must have thorough knowledge of the subject. That is true. There's no alternative. 
For video, the documentarian must be a video expert.

> You need to cope with (gradual and sometimes sweeping) change and
> especially for projects like FFmpeg that means big restructurings
> in the documentation every so often.

Complete rewrites are very rare. Even if a project is a complete rewrite, the steps are the same. 
There should be no mysteries.

Coders should not write documentation.

More information about the ffmpeg-user mailing list