[FFmpeg-user] where to post suggestion for the documentation?

Steve Newcomb 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 mailing list