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
_______________________________________________
ffmpeg-user mailing list
ffmpeg-user@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-user
To unsubscribe, visit link above, or email
ffmpeg-user-requ...@ffmpeg.org with subject "unsubscribe".
