[FFmpeg-user] Filter documentation -- PTSs

[Rob Hallam]

On Mon, 15 Feb 2021 at 14:48, Phil Rhodes via ffmpeg-user <
ffmpeg-user at ffmpeg.org> wrote:

>>  On Monday, 15 February 2021, 13:58:30 GMT, Michael Koch <
astroelectronic at t-online.de> wrote:
>>  A few developers (not all!) are actively fighting against any changes
in the documentation. It seems
>>  they are really convinced that the documentation is perfect as it is.

> The ffmpeg example is very extreme but I don't really see what can be
done about it. It's their project. They can do anything they want.

Absolutely true.

There is always the suboptimal option of creating parallel documentation.

There's a number of options that can coexist and sometimes overlap, off the
top of my head:
 - individual collections of examples and observations (like Michael Koch's
PDF or the glossary Mark Filipak was/is thinking of creating; or something
like the Arch wiki's examples)
 - parallels/forks of official facets of documentation (eg "The Unofficial
FFmpeg Wiki", ordocumentation)
 - self-answered questions on QA sites that serve as examples of a
particular filter, features, etc

There are other options too, but they are all also suboptimal [1]. Will
people actually use them? [2] Will they be accurate if they are written and
supported by people with an incomplete understanding of the codebase? Would
it have enough people on board to fully support the endeavour- that is
write it and maintain it?

The barrier to entry is low, as all you need is space on a webserver [3].
But considering the fate of most forks, it's worth asking: is it worth it?
In some ways, it might be beneficial for all involved (from both FFmpeg and
those wanting to improve it POV) as it might obviate certain frustrations
on both sides.

Different projects have different documentation philosophies. Project A
might prefer to be terse at the cost of lacking information for some users;
whereas Project B might prefer to be verbose at the cost of potential
inaccuracy.

I don't endorse a particular action, I don't suggest a particular
philosophy is best; this is just food for thought.

Take care,
Rob

[1] : I recall someone setting up a Discord channel for troubleshooting
FFmpeg issues a couple of years ago, though an IRC channel already existed.
There's very little to stop someone doing something similar with forums, QA
software, or whatever. Because while the mailing list works, is searchable,
and can be very helpful; it does have a few pain points around top-posting,
folks needing reminded to use up-to-date versions of ffmpeg, including full
uncut output, not using -hide_banner etc.

Heck, every time I mail the list I'm not sure whether to manually break
lines at 72 characters or not.

[2]: When writing this I went to look something else up, and by chance
stumbled upon this comment thread from a day ago:
https://old.reddit.com/r/linux/comments/lj4v0w/some_nifty_stuff_ffmpeg_can_do/gnbkbwe
(tl;dr - P1: ffmpeg is awesome! P2: it is, tho I wish the docs were
better...)

[3]: Admittedly you need the funds to rent this space and associated
bandwidth and any domains, knowledge of keeping things secure and updated
and free of spam, etc