[FFmpeg-user] A systematic effort for documentation? [was: Re: Why is format=rgb24 required after maskedmerge?]

[Jim DeLaHunt]

On 2020-08-21 08:08, Gyan Doshi wrote:
>
> On 21-08-2020 07:12 pm, Mark Filipak wrote:
>> On 08/21/2020 06:44 AM, Gyan Doshi wrote:
>>>
>>> On 21-08-2020 04:03 pm, Michael Koch wrote:
>>>> Am 21.08.2020 um 12:09 schrieb Gyan Doshi:
>>>>> …
>>>>> FFmpeg's documentation is very incomplete. I had a rough roadmap 
>>>>> at the start of the year for plugging the gaps, but other events 
>>>>> transpired.
>>>>>
>>>>> I hope to start a systematic effort in September.
>>
>> May I assist you?
>
> Sure. Do you already have a set of tasks / actions in mind?

Gyan, it's great to hear that you say that FFmpeg's documentation is 
very incomplete. Acknowledging the problem is a first step that not 
enough people are taking.

It's also great to hear that you are considering a systematic effort for 
documentation. I encourage you to set up a structure that allows others 
to contribute, and to ask for contributions. Consider offering to act as 
champion and mentor for the other contributors. Not everyone on the 
ffmpeg-devel list will be kind to them.

I have a few suggestions for tasks and actions to consider:

Scope is potentially quite large, including refactoring the structure of 
the documentation in a big way.  I'm in favour of breaking up the video 
filter documentation so that each filter has its own page and URL, for 
example. I expect that documentation which fully explains FFmpeg 
functionality would be about as sprawling as the Python language 
documentation [1], especially [2]. Consider how large of a scope you 
want to attempt. Consider how to divide large scope into incremental 
steps which are usable as work is under way.

Think about what you will do if you trigger immune responses. "It's 
different, it must be wrong" might be a reaction. You carry some weight 
and respect among FFmpeg committers, which helps. Consider if that will 
be enough, or if you need to take some steps to get buy-in to make the 
changes you want to make.

There is a great need for a glossary. It should be structured so that 
each term has an anchor, allowing references from anywhere in the 
documentation to the glossary. My nomination for entries: "fps", "GOP", 
"PTS", "time base".

An introduction to digital video concepts and vocabulary would be 
helpful. Writing something new would be great, but even links to some 
other documents and presentations with good concepts and vocab is a lot 
better than nothing. I nominate a link to /"/A Guide to MPEG 
Fundamentals and Protocol Analysis", by Tektronix [3].

Consider how you want to trade off the virtues of brevity and accuracy. 
Compare two descriptions of the fps video filter: the official doc at 
[4] (232 words) vs a rewrite at [5], in draft patch form at [6] (1258 
words).  The primary review response to the rewrite was: too many words, 
we don't want FFmpeg doc to be that detailed. I think the official doc 
is incomplete, it doesn't describe all of the fps filter functionality 
and parameters. How do you want to make that trade-off?

A minor pushback to the "fps" filter doc rewrite at [6] was that general 
terminology should link to a centralised descriptions instead of being 
spelled out where used. There is another trade off between here, between 
brevity overall, along with consistency guaranteed by structure, versus 
ease of having the description at point of use. How do you want to make 
that trade-off?  And, do you make the trade-off differently when the 
centralised descriptions (Glossary, AVOptions writeup) don't yet exist?  
For instance, should an "fps" filter rewrite just not attempt to explain 
or link general terminology until the glossary is in place, or should we 
accept in-place explanation for now, knowing that the glossary will make 
it redundant once it arrives?

The draft rewrite at [6] is of course available as a starting point for 
whoever wants to ride into that valley of death[7] again.

The syntax and behaviour of filterchains has documentation which is 
correct, but very terse and hard to follow. Rewriting this with clearer 
text, and better diagrams, would be a big improvement. This will make it 
longer as a consequence. That is a trade-off.

The syntax and behaviour of the `ffmpeg` general options is a jumble and 
very hard to follow. It would be easier to understand if it was broken 
into different sections by function.  This will make it longer as a 
consequence. That is a trade-off.

Consider all the pockets of documentation sprinkled throughout the 
FFmpeg corpus. There is a lot of documentation in the executable, 
reached by `ffmpeg -formats` and the like. Do you want to try to allow 
for a build process which injects this documentation into the HTML files 
as well?

Gyan, I respect you greatly for your helpfulness here, and also on 
StackOverflow, and for the way you avoid the negative behaviour of some 
other participants. You represent the better angels of this community. I 
hope these ideas are helpful for you. I wish you good fortune in this 
project. I'm glad to help, if there is a way I can avoid being the 
trigger for the immune response.

       —Jim DeLaHunt, software engineer, Vancouver, Canada


[1] https://docs.python.org/3/

[2] https://docs.python.org/3/library/index.html

[3] 
https://www.tek.com/document/primer/guide-mpeg-fundamentals-and-protocol-analysis

[4] http://ffmpeg.org/ffmpeg-filters.html#fps

[5] http://blog.jdlh.com/en/2020/04/30/ffmpeg-fps-documented/

[6] http://ffmpeg.org/pipermail/ffmpeg-devel/2020-May/261811.html

[7] 
https://www.poetryfoundation.org/poems/45319/the-charge-of-the-light-brigade