[FFmpeg-user] "documented implicitly" part 2 [was: Re: Problem while converting DNG sequnece to video file]

Nicolas George george at nsup.org
Fri Aug 21 13:28:37 EEST 2020


Jim DeLaHunt (12020-08-20):
> Nicolas, do you remember this?
> 
> On 2020-05-01 03:01, Nicolas George wrote [1]:
> > 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.
> > …

Now that you mention, it, I remember. The fact that I did not find it
while searching my archives is caused by a misconfiguration of Git in
your end:

From: list+ffmpeg-dev at jdlh.com
From: Jim DeLaHunt <list+ffmpeg-dev at jdlh.com>

> I will observe that you didn't actually review the documentation patch which
> led to that thread. You just latched on to Carl Eugen's "who really profits"
> comment, and complained. That patch was not my only experience submitting a
> documentation improvement and having the FFmpeg project's antibodies reject
> it. But it did vividly clarify for me what the project values and what it
> does not.

I stand by my assessment, and reading a little more of your proposal and
your attitude in this discussion confirms that you have the wrong
attitude to both submitting patches and writing documentation.

There are many components, filters and others, that take a frame rate
option. How should it be documented? Should we add a little information
about these values in the documentation at each place?

It would be terrible for developers, who would have to update dozens of
places each time something changes about it. It would be terrible for
users, who would be exposed to subtly inconsistent information depending
on which part of the documentation they read. Inconsistency is one of
the worst forms of bad documentation, and redundancy invariably devolves
into inconsistency. This is what you were proposing.

The proper way to document this option is to explain the syntax of a
frame rate at a central place, along with the syntax of a video size,
the syntax of a duration, etc., and to have a link to there in the
documentation of each option using that syntax.

If it is done that way, it is best for most users:

- Confirmed users already know the syntax of a frame rate, they do not
  need to waste their time re-reading it just in case there is a subtle
  difference there.

- Confirmed users who need to refresh their memory follow the link.

- Beginners realize they need to learn the syntax of a frame rate,
  follow the link and learn it. They would have their solution, and it
  would work for all similar filters. They would have learnt something
  and made a step towards becoming confirmed users.

- As for users who just want the answer right now to their tiny
  question, without realizing there is a bigger picture, a consistency
  in syntax of options, I call them lazy and I stick with it. We are
  talking about following a link, not "having to become an FFmpeg
  developer" nor "read the source" as you strawmanishly put it.

The same issue applies to most of your proposal: you wanted to explain
basic concepts about video streams. These concepts deserve to be
explained, BUT NOT IN THE DOCUMENTATION OF A SPECIFIC FILTER.

They belong in an introduction chapter, with links from places where it
is relevant. If you do it that way, and the contents makes sense, it
will be accepted.

And this is where we come to your approach to submitting patches: you
were told, in a very succinct way, that you were wrong. You were
expected to understand how, but you were welcome to ask clarification. I
would have explained what I just explained, and pointed that the
documentation for the syntax of a frame rate already exists:
http://ffmpeg.org/ffmpeg-all.html#Video-rate
But instead, you attacked.

This is up to you: you can contribute, or you can not contribute. But if
you decide not to and still criticize, do not be surprised to get
scorned. And if you do, learn to take criticism. And, in the case of
documentation, learn to think it as a whole. Good documentation should
not contain the answer to users' questions, it should contain the tools
for users to answer their own questions. Those who refuse to use these
tools are lazy, do not cater for them.

-- 
  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-user/attachments/20200821/6c6a5f7c/attachment.sig>


More information about the ffmpeg-user mailing list