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

Jim DeLaHunt list+ffmpeg-user at jdlh.com
Fri Aug 21 00:03:53 EEST 2020

On 2020-08-20 09:03, Alexander Strasser wrote:

> 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!

I very much agree: it is incredibly hard.

An important companion observation: it is valuable. It multiplies the 
value of the executable code, because it makes users and other 
developers able to get more value from the existing executable code by 
using it better.

> 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.
> You need to have enough multimedia knowledge and experience
> so you can try things yourself and write things in sufficiently
> understood language.

True, but also don't underestimate the power of collaboration. A subject 
matter expert can empower a writer (or a software developer for that 
matter) who is not expert, through suggestion of introductory reading 
material on the subject, through explaining the subject, and through 
reading draft documentation (or reviewing proposed code changes). 
Someone who is both subject matter expert and writer (developer) is a 
bit of a unicorn, but with collaboration you don't have to wait for 
unicorns to appear.

Also, you need a project which sees documentation as a necessary and 
valuable part of the complete product. You need champions who will 
support the writers in making their contribution and will review 
patches. You need patch-review gatekeepers who will not veto better 
documentation. You need general project agreement that better will be 
different than current, and that different is OK.

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

True, but I believe this is no different than preserving runtime 
performance, or memory use, or avoidance of memory leaks, or avoidance 
of functionality regressions. Coping boils down to insisting that 
contributions need to be more than just code which compiles and runs. 
They need to have unit tests, they need to pass functionality and memory 
tests, they need to have documentation. And the project needs to track 
technical debt in documentation, and be prepared to pay it down from 
time to time.

How does the FFmpeg project cope with these other desirable features? 
How well does it work?

More information about the ffmpeg-user mailing list