[FFmpeg-user] where to post suggestion for the documentation?
srn at coolheads.com
Tue Nov 3 17:07:05 EET 2020
On 11/2/20 5:04 PM, Jim DeLaHunt wrote:
> > FFmpeg's documentation is not a a beginner's course to Unix. Learn
> to use your operating system.
> Zero concession that the documentation omits useful information. Zero
> acknowledgement that the documentation should have a goal to help
> users succeed when using FFmpeg. 100% blame on user's ignorance for
> the obstacle.
Thanks for your kind and consoling words, Jim, and for recognizing that
the response to my suggestion was helpful to nobody, and a poor way to
treat anyone's first attempt to contribute.
I've been using and learning Unix since probably 30 years before the
benighted respondent was born, but I chose not to respond at all. To
deal positively with immature behavior, one must first recognize that
/every /response to /any /behavior /reinforces that behavior/. (Thank
you, B.F. Skinner, for that vital insight.)
Having made contributions to another of the world's Great Projects,
namely Python, I'm more used to a project culture that emphasizes
usability, and therefore documentation. The software developers of
Great Projects should not have to shoulder the enormous burden of
supporting usability -- of dealing with the innumerable knowledge
deficiencies (or, in my own case, forgetfulnesses) of their software's
users. (N.B. UX -- user experience -- is now a field unto itself, and
about time, too.) <https://www.youtube.com/watch?v=1Z8gbVnrTfE>
It is no easier to contribute to Python's documentation than it is to
improve Python's technology, but at least it isn't harder. Python
certainly has elevated its documentation effort to co-equal status with
all its other aspects/, and//, overall, Python's documentation
demonstrates phenomenal editorial discipline and uniform excellence,
/even while forever remaining a work in progress/.///I feel satisfaction
in having made minor contributions to it, even though it was not easy to
get my suggestions accepted. I had to convince the editorial powers,
arguing in terms of their own stated values and goals.
It's a pity that it's apparently so hard to help out with ffmpeg's
documentation, even trivially. Since I came to ffmpeg so recently, my
perspective allows me to assure you that ffmpeg's documentation is
hellishly inscrutable for anyone who arrives fresh, with a pile of media
data in one hand, a trivial problem in the other, and little experience
with either. Maybe that's not important to ffmpeg's leading lights, but
it should be. Even though Ffmpeg is not an end-user application, it
should not excuse itself from having first-class documentation. Python
isn't an end-user application, either.
More information about the ffmpeg-user