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
