[FFmpeg-user] "documented implicitly" [was: Re: Why is format=rgb24 required after maskedmerge?]

[Alexander Strasser]

On 2020-08-20 14:03 -0700, Jim DeLaHunt wrote:
> On 2020-08-20 09:03, Alexander Strasser wrote:
>
> > I will bring up a point that has become clear to me.
> >
> > Good documentation in general and especially for software is
> > incredibly hard to write and get right!
>
> I very much agree: it is incredibly hard.
>
> An important companion observation: it is valuable. It multiplies the value
> of the executable code, because it makes users and other developers able to
> get more value from the existing executable code by using it better.

I very much agree too. There has probably never been a widely
successful software without the critical amount of docs needed.

That docs weren't always written in the software projects
themselves, but it has always been written AFAICT.

So yes, good documentation is very valuable in multiple ways!


> > In general you have to be a good writer and have sufficient
> > insight into the tech you are documenting. And this means for
> > FFmpeg you need to understand C enough, so you can roughly
> > read the code and are able to ask the right questions.
> >
> > You need to have enough multimedia knowledge and experience
> > so you can try things yourself and write things in sufficiently
> > understood language.
>
>
> True, but also don't underestimate the power of collaboration. A subject
> matter expert can empower a writer (or a software developer for that matter)
> who is not expert, through suggestion of introductory reading material on
> the subject, through explaining the subject, and through reading draft
> documentation (or reviewing proposed code changes). Someone who is both
> subject matter expert and writer (developer) is a bit of a unicorn, but with
> collaboration you don't have to wait for unicorns to appear.
>
> Also, you need a project which sees documentation as a necessary and
> valuable part of the complete product. You need champions who will support
> the writers in making their contribution and will review patches. You need
> patch-review gatekeepers who will not veto better documentation. You need
> general project agreement that better will be different than current, and
> that different is OK.

Good point. I intended to mention collab initially, but seems I
ditched it to keep my reply short.

I have occasionally seen this model work for some time, but it's
nothing to be taken for granted. Especially in a big distributed
open source project environment.


> > You need to cope with (gradual and sometimes sweeping) change and
> > especially for projects like FFmpeg that means big restructurings
> > in the documentation every so often.
>
>
> True, but I believe this is no different than preserving runtime
> performance, or memory use, or avoidance of memory leaks, or avoidance of
> functionality regressions. Coping boils down to insisting that contributions
> need to be more than just code which compiles and runs. They need to have
> unit tests, they need to pass functionality and memory tests, they need to
> have documentation. And the project needs to track technical debt in
> documentation, and be prepared to pay it down from time to time.

No disagreement in general.

Though trade-offs are always needed.


> How does the FFmpeg project cope with these other desirable features? How
> well does it work?

Mostly good I would say. In short FFmpeg isn't used in such a wide
variety of software on different hardware by so many users for such
a long time for no reason.

Is FFmpeg perfect? No, it isn't for sure.
Is FFmpeg's documentation perfect? Surely not.

I hope the documentation can be improved for good. There is always
tension in a project like FFmpeg and there is no one voice of the
project, which is actually not bad thing.

The FFmpeg documenation isn't exactly bad, and it has been rather
gracefully extended over the years.

So help in improving the docs is welcome, just don't expect it to
be easy or all proposed changes to be immediately accepted. The FFmpeg
project insists very much on review of patches and therefore things
may need some arguing and iterations, or sometimes will be dropped.


Best regards,
  Alexander