[FFmpeg-devel] Who is the FFmpeg documentation for? [was: Re: [PATCH v2] doc/filters.texi: complete rewrite of fps filter doc, v2.]

[Jim DeLaHunt]

On 2020-05-01 03:01, Nicolas George wrote:

> Carl Eugen Hoyos (12020-05-01):
>>> -The desired output frame rate. The default is @code{25}.
>>> +The output frame rate, in frames per second. May be an integer, real, or
>>> +rational number, or an abbreviation. The default is @code{25}.
>> I seriously wonder who really profits from this change but it may be ok.
> I would argue: lazy beginners.
>
> Non-beginners already know what a frame rate is, it completely basic
> stuff.

Nicolas, I strongly disagree with the term "lazy beginners". This points 
to a much larger question: who is the FFmpeg documentation for?

FFmpeg is used by a lot of people. A few of them are FFmpeg core 
developers, who have read the ffmpeg/ source code top to bottom. A few 
more are experts in digital video, who have worked deeply with the 
terminology of the MPEG-2 or H.264 specs. But a lot are ordinary people 
who just want to fix a video, or convert a file format, or connect to a 
camera. They are doing other things with their life than spending many 
hours learning the ffmpeg/ code and MPEG terminology.

This does not make them "lazy". What a condescending thing to say!

And, even though a term like "frame rate" brings up an intuitive 
meaning, it is reasonable that different people might have different 
intuitive meanings. There is value to stating the meaning explicitly. 
One thing that geniuses sometimes do is explain the simple things 
clearly, so that everyone gets the same meaning, and has a strong 
foundation to build on.  For FFmpeg documentation to define fundamental 
terms is not weakness.

Does this project want the documentation to be for all the FFmpeg users? 
Then it must aim to make it meaningful, even to beginners.


> Beginners who want to achieve something by themselves will peruse
> https://ffmpeg.org/ffmpeg-all.html#Video-rate and now know what a frame
> rate is.


Which ordinary user, coming to FFmpeg to accomplish a task rather than 
to learn all about FFmpeg's source code, will read 
https://ffmpeg.org/ffmpeg-all.html from top to bottom until they come 
across the #Video-rate section? Note that the existing *fps* filter doc 
does not link to #Video-rate. How do you expect a beginner to find 
FFmpeg's definition of basic terms?  The doc lacks a Glossary, it lacks 
a Concepts Guide, it lacks a Tutorial, it lacks systematic cross 
references from terms used to definitions.

So what you are saying is, the documentation is not for "lazy" 
beginners, it is only for beginners who are willing to pay the time to 
read the doc top to bottom, or to get a PhD in MPEG. And that excludes 
many, many FFmpeg users.


> If we want to enhance this, we just have to make sure the doc for every
> AV_OPT_TYPE_VIDEO_RATE option has a link to #Video-rate. Nothing more.

I will agree with you on the value of links from parameters to sections 
explaining the details of the types and values of that parameter. Note 
that my patch to the *fps* doc includes such a link. Note also that not 
every potential target of such a link includes an anchor: video filter 
/settb/ does not, for example.

I think those links are helpful, but not sufficient.

> Duplicating the explanations is a waste of everybody's time.
It is not a waste of time for the user who comes to FFmpeg wanting to 
get a task completed. But who is the FFmpeg documentation for? Is it for 
those users? Or is it just for the FFmpeg core developers? When you say 
"everybody", who do you include?
> (I dream of a system where the doc would be not in a separate tree but
> built as part of the library, and links like that happen automatically.)
>
> Regards,
>
Best regards,

      —Jim DeLaHunt, software engineer, Vancouver, Canada