On 2020-08-20 09:03, Alexander Strasser wrote:
I will bring up a point that has become clear to me.
Good documentation in general and especially for software is
incredibly hard to write and get right!
I very much agree: it is incredibly hard.
An important companion observation: it is valuable. It multiplies the
value of the executable code, because it makes users and other
developers able to get more value from the existing executable code by
using it better.
In general you have to be a good writer and have sufficient
insight into the tech you are documenting. And this means for
FFmpeg you need to understand C enough, so you can roughly
read the code and are able to ask the right questions.
You need to have enough multimedia knowledge and experience
so you can try things yourself and write things in sufficiently
understood language.
True, but also don't underestimate the power of collaboration. A subject
matter expert can empower a writer (or a software developer for that
matter) who is not expert, through suggestion of introductory reading
material on the subject, through explaining the subject, and through
reading draft documentation (or reviewing proposed code changes).
Someone who is both subject matter expert and writer (developer) is a
bit of a unicorn, but with collaboration you don't have to wait for
unicorns to appear.
Also, you need a project which sees documentation as a necessary and
valuable part of the complete product. You need champions who will
support the writers in making their contribution and will review
patches. You need patch-review gatekeepers who will not veto better
documentation. You need general project agreement that better will be
different than current, and that different is OK.
You need to cope with (gradual and sometimes sweeping) change and
especially for projects like FFmpeg that means big restructurings
in the documentation every so often.
True, but I believe this is no different than preserving runtime
performance, or memory use, or avoidance of memory leaks, or avoidance
of functionality regressions. Coping boils down to insisting that
contributions need to be more than just code which compiles and runs.
They need to have unit tests, they need to pass functionality and memory
tests, they need to have documentation. And the project needs to track
technical debt in documentation, and be prepared to pay it down from
time to time.
How does the FFmpeg project cope with these other desirable features?
How well does it work?
_______________________________________________
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".
