[FFmpeg-devel] [RFC] 5 year plan & Inovation

[Andrew Sayers]

On 18/04/2024 10:13, epirat07 at gmail.com wrote:
> On 18 Apr 2024, at 9:52, Stefano Sabatini wrote:
>> On date Wednesday 2024-04-17 17:24:02 +0100, Andrew Sayers wrote:
>>> On 17/04/2024 14:58, Michael Niedermayer wrote:
>> [...]
>>> I've occasionally tried getting into ffmpeg for over a decade now, and have
>>> lurked here for the past few months as I put in the effort to grok it.
>>> On behalf of people who could contribute but don't, I'd like to suggest
>>> ffmpeg focus on *learnability*.
>>>
[...]
>>> But other issues seem like quick wins - for example I've lost count of
>>> all the times I typed two functions into Google, spent hours trying to
>>> make them work together, then finally realised I was looking at the
>>> documentation for 3.0 in one tab and 5.0 in the other.  Surely you can
>>> just add a line to the top of the documentation like "click here to see
>>> the trunk version of this file"?
>> Functions are documented in doxygen, so they depend on the major.minor
>> version, while you seem to refer to the FFmpeg version. Also on the
>> website we usually only have the latest mainline documentation, so I
>> don't understand how can you have different versions in different tabs
>> (unless you didn't update that tab since months/years).
> Thats not true and same things has happened to me multiple times,
> thats why I always have to check the URL to make sure the docs
> are the ones for master or latest release I am working with.
>
> For example see this ancient documentation here:
> https://ffmpeg.org/doxygen/1.2/index.html

I'm glad I'm not the only one making that mistake!  In fact, older versions
don't just exist, they're often the first link in Google.  For example,
typing "avformat_init_output" into Google and clicking on the first link
takes me to [1] (version 3.2).

The website doesn't have documentation for 6.1 or 7.0 ([2] and [3]),
which might have made it look like only trunk is supported?  I agree
older versions should be documented (and 6.1/7.0 added), because
sometimes you need to develop software that works with older versions,
so you *want* to compare documentation between two tabs.

If people reading the documentation should think in terms of major.minor,
how about automatically editing the PROJECT_NUMBER in doc/Doxyfile to
include that information?  That wouldn't be obvious enough to solve
the "two tabs" problem (e.g. I've had it with 1.0 documentation before now,
even though the formatting is completely different), but it would at least
mean the information is available on the page.


> We generate those for each FFmpeg version afaik, not MAJOR-MINOR of the
> libraries:
>
> https://ffmpeg.org/doxygen/6.0/index.html
>
> Maybe Michael can clarify, as I have no way to check how these are actually
> generated for the website, if this is by branch of some other logic or
> completely manual.
>
> I do agree with OP that it would be VERY helpful to have some note there on
> old docs or some overview of the different versions at least, so that its clear
> you are looking at older ones…
Without getting too far off-topic, I would also be interested in knowing 
how docs are actually generated in practice. I've tried generating 
documentation locally and making cross-references between versions, but 
some functionality is hidden behind #ifdef's (e.g. deprecations), and 
I've never been able to work out the exact magic words the site uses. 
Also, the anchors for individual functions on the site don't always 
match the ones generated locally, so I can't e.g. create my own docs and 
link to the public ones. [snip - useful information about contexts] Well 
now I guess I have to stop procrastinating! I'll write up my 
understanding (which is probably still a bit wrong) and send in a patch 
for discussion.
>>> To bring this back to ffmpeg development - I made a note to write a
>>> patch saying they were synonyms and linking that explanation from
>>> e.g. AVCodecContext, but the job has been rotting away in my todo list
>>> for a month now waiting for me to be "sure I've got it right" (i.e. to
>>> give up a perfect excuse for procrastination).  To be blunt, on some
>>> level it feels like I've put more in than I've got out of that problem,
>>> and haven't been able to psych myself up to submit a patch that could
>>> get me laughed out of the room (or worse, politely ignored).  If the
>>> project was otherwise easy-to-learn, I would have felt a much stronger
>>> sense of obligation to pay that back.
>> This looks like the usual pattern: experienced API developers don't
>> feel the need to improve the docs, so they have no real incentives to
>> do so; outsiders might need to improve it, but this means to
>> understand the intricacies of the framework, and by the time they got
>> it they probably don't need it anymore.
>>
>> Also writing good documentation - as writing good prose - is *hard*,
>> but in general bad is better than nothing.

I agree writing good documentation is hard, but IMHO FFmpeg's problem
is just about optimisation, which people round here are excellent at.
Whether optimising code or docs, you step through the process the hardware
(reader) goes through, look for wasted cycles, and fix those places.
Sometimes the solution is highly technical (spend a week learning about
SIMD or active language), but most of the time it's trivial (move a test
to an outer loop or add a link from the place where people look for it).

I bring this up here because I've seen experienced developers on the list
mention the need to bring in newbies, which means improving learnability
(mostly docs, but e.g. all the special cases in the code are problems too).
So hopefully a 5 year plan can emphasise the (indirect) need amongst people
who can do something about it.

 	- Andrew Sayers

[1] https://ffmpeg.org/doxygen/3.2/group__lavf__encoding.html
[2] https://ffmpeg.org/doxygen/6.1/
[3] https://ffmpeg.org/doxygen/7.0/