Documentation redux
I think you’re missing a couple of things.
First, for many of us, writing documentation is hard. I know it is for me. I write, and it comes out crap. I rewrite, and it’s only slightly better. I work and slave, and spend tons of time, and it never gets better than “decent.”
Second, and partly related to the first, many of us find writing documentation to be less than fun. Personally, I hate it with a passion, and the worst part of any project at work is writing the doc parts of it. I never liked writing in school, and I don’t like writing now.
Third, writing documentation for Open Source projects requres a fair amount of technical ability and a fairly deep knowledge of the software being documented. This generally narrows down the list of people who have the knowledge to write good docs to those who also have the ability to code. And, for the overwhelming majority of us, coding is much more fun than docs. So, we code.
I think maybe a solution is to encourage people to become doc people, rather than devs. Sort of like the AT program, mentor people into the doc program. If there were enough people who could clean up and polish my docs, I might be more interested in whipping up a technical description of something, which would be crap (see point one above), and passing it on to someone who can actually write.
In general, FOSS has been about scratching itches, and the doc itch doesn’t seem to be scratched as much as the code itch. I know, in my case, if worst comes to worst, I can read the code.
Discussion Area - Leave a Comment