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

[Nicolas George]

Jim DeLaHunt (12020-05-02):
> Nicolas, I strongly disagree with the term "lazy beginners". This points to
> a much larger question: who is the FFmpeg documentation for?

Subscribe to ffmpeg-user, do support there, and then tell me if there
are no lazy users.

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

What makes them lazy is not perusing the documentation when they need
it. What makes them lazy is being angry if they do not find exactly what
they need in the documentation.

Most users are not like that fortunately. But some are. We should not
indulge them.

> There is value to stating the meaning explicitly.

I have not objected in stating the meaning explicitly. I have objected
to having the meaning repeated.

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

Could you please burn straw men elsewhere? This is not what I have
suggested at all.

>			   Note that the existing *fps* filter doc does not
> link to #Video-rate.

Well, fix that!

>			      The doc lacks a Glossary, it lacks a Concepts
> Guide, it lacks a Tutorial, it lacks systematic cross references from terms
> used to definitions.

Then add them.

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

Please burn your straw men elsewhere.

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

The link is good.

>						  Note also that not every
> potential target of such a link includes an anchor: video filter /settb/
> does not, for example.

Then add the anchor.

> I think those links are helpful, but not sufficient.

They are.

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

The documentation is for users who look for information. As such, it
should be terse and to the point. Extra chatter distract from the actual
info.

The only thing worse than a documentation that repeats a dozen times the
same thing is a documentation that repeats a dozen times the same thing
with subtle inconsistencies.

Make "frame rate" a link to the definition and syntax of "frame rate" in
the scope of FFmpeg's documentation, and do not duplicate a word of it.
Normal users will follow the link, because they need the syntax anyway.
Lazy users can go use a GUI.

Regards,

-- 
  Nicolas George
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20200505/8b777dd9/attachment.sig>