[FFmpeg-user] Some more thoughts on documentation

[Jim DeLaHunt]

On 2020-08-23 11:07, Carl Zwanzig wrote:
> …I'm fairly sure that someone will object to a point below. Go ahead, 
> but also suggest something better….
> …Original content:
> …
> Process to create output docs:
> …
> Output organization & formats:
> …
> "Rules of the game"? …
> …

This sounds like fun. I'll play!

I think it would help to state explicitly some fairly fundamental 
premises. We should state that documentation is important, and adds 
value to the project. Something along the lines of a vision and mission 
and values statement for the documentation effort. In most projects this 
would go without saying, but in the FFmpeg project I believe these 
premises aren't accepted by everyone. Sooner or later in some patch 
debate, we will have to appeal to these premises to justify a 
documentation change.

I think it would help to write down personas[1], in the sense of 
interaction design, to explain who we think reads the documentation. 
This will help us make decisions about what level of detail is 
appropriate, and what kind of material to include. One persona is the 
person who isn't interested in the details of digital video, they just 
want to convert from format A to format B, and heard ffmpeg could do 
that. Another persona is the digital video specialist who is looking for 
a versatile processing tool. Another persona is the system integrator 
connecting a camera type A to streaming channel B with FFmpeg providing 
the glue. Another persona is the devops expert at BigComputerCompany who 
is deploying FFmpeg to a cloud-based image processing pipeline. Another 
persona is the digital media software developer who is working on adding 
support for format X to Ffmpeg. And so on. By defining these personas, 
we defend their needs against those who might dismiss them as "lazy 
beginners".

I think it would help to articulate quality standards for the 
documentation. For instance, documentation must be complete. Every 
parameter to a filter or format must be included in the documentation, 
and no parameter may be in the documentation which is not supported by 
the software. Every data type or keyword accepted by a parameter must be 
defined in the documentation or via at most one click on a hyperlink. Etc.

I think it would help to come up with a different global structure for 
the documentation. Separate tutorial, and cookbook, and reference 
material. Build a chapter and section structure which suits the content 
we actually have (the present structure looks like the outcome of a lot 
of accretion over time without restructuring). Come up with a URL scheme 
that permits effective cross-linking to shared definitions, with URLs 
that are stable over time.

I think there is no escaping that people are going to be using a lot of 
different versions of FFmpeg. It is desirable to snapshot the 
documentation at major version changes, so that someone with an old 
version of FFmpeg has a chance of finding an old version of the docs 
that matches their software.

Those are a few thoughts to add to the conversation.

[1] 
https://www.interaction-design.org/literature/article/personas-why-and-how-you-should-use-them