Eric Raymond Stumped By Documentation's 'Reproduction' Problem
Eric Raymond has been working on a tool called reposurgeon for editing version-control repository histories -- those "risky operations that version-control systems don't want to let you do." But this led to some interesting thoughts about documentation: "Why doesn't reposurgeon have easy introductory documentation" would normally have a simple answer: because the author, like all too many programmers, hates writing documentation, has never gotten very good at it, and will evade frantically when under pressure to try. But in my case none of that description is even slightly true. Like Donald Knuth, I consider writing good documentation an integral and enjoyable part of the art of software engineering. If you don't learn to do it well you are short-changing not just your users but yourself... If you go looking for gdb intro documentation, you'll find it's also pretty terrible. Examples of a few basic commands is all they can do; you never get an entire worked example of using gdb to identify and fix a failure point. And why is this....? High-quality introductory software documentation depends on worked examples that are understandable and reproducible. If your software's problem domain features serious technical barriers to mounting and stuffing a gallery of reproducible examples, you have a problem that even great willingness and excellent writing skills can't fix. Of course my punchline is that reposurgeon has this problem, and arguably an even worse example of it than gdb's. How would you make a worked example of a repository conversion that is both nontrivial and reproducible? What would that even look like...? Having identified the deep problem, I'd love to be able to say something revelatory and upbeat about how to solve it.... Unfortunately, at this point I am out of answers. Perhaps the regulars on my blog will come up with some interesting angle.
from Slashdot https://ift.tt/38UD7pw
Read more of this story at Slashdot.
from Slashdot https://ift.tt/38UD7pw
0 Response to "Eric Raymond Stumped By Documentation's 'Reproduction' Problem"
Post a Comment