Where is the documentation?
I’ve been thinking lately about documentation for open-source projects.
Most of my open-source contributions are code-based, but occasionally I write or contribute to documentation. Yet the email feedback I recieve is pretty much 100% about documentation that I have written as opposed to code I have developed. I get people just saying ‘thanks’, people giving suggestions, people asking permission to republish it elsewhere, people providing translations, its fantastic and much appreciated.
I had a recent conversation with roger55 on IRC which went something like:
<roger55> hey dsd, i just got back from linuxtage graz, it seems you have a few fans out here
<dsd> roger55: cool! what were they saying?
<roger55> dsd: they love the guides you write
ahem.. I write lots of code as well!! ;)
The documentation/documentation-user seems to be a much more thriving and active community than the developer/software-user community, and from my perspective, documentation authors get a lot more feedback and direct communication with the users. Writing documentation for an open-source project is an exciting and valuable contribution you can make. Tag your email address on the end and you’ll really know when people are benefitting from your work.
The question I am posing: Why are there so few open source documentation writers in comparison to software developers? Using Gentoo as an example, we have just 15-20 core documentation writers, compared to hundreds of developers who deal with software code and maintenance. Not using Gentoo as an example, many open source projects lack comprehensive and up-to-date documentation, and a lot of existing documentation is written by software developers who write it in response to being asked the same questions repeatedly.
Writing code is a specialist thing. In the UK, you don’t really get taught how to do it until your 14th year of full time education. It’s very technical and you need to be skilled and have a good knowledge of computers to be an effective developer.
Yet language and literacy is something you are taught throughout education and life, and using software is a daily thing for many people. No offense to the skilled documentation authors out there, but I don’t see it as such a specialist activity. So where is the mass of documentors, and do they know what they are missing out on?
June 16th, 2005 at 2:54 pm
I, for one, am still trying to wade through man(5) ebuild, so I can maintain stuff, e.g. lilypond.
In other words, the entry level documentation could use focus.
To ATFQ, communicating with other people clearly is more challenging than talking to an interpreter/compiler.
Best,
Chris
June 16th, 2005 at 3:44 pm
[...] 6/16/2005 Documentation redux Filed under: Gentoo — Daniel @ 10:42 am Daniel I think you’re missing a couple of things. First, [...]
June 18th, 2005 at 10:32 am
Being one of the guys from grazer linuxday I can say that I know and use not only your documentation but the code as well. ;) I especially like http://dev.gentoo.org/~dsd/gentoo-dev-sources/releases.htm which provides an exellent base for my kernelwork on grml (see http://grml.org/) and of course ‘Writing udev rules’. The documentation of gentoo is very nice in general.
June 18th, 2005 at 6:28 pm
[...] dsd’s weblog throw the sailors overboard « Where is the documentation? Documentation again [...]
June 19th, 2005 at 2:28 pm
Dude.. if you ever want to make your docs published in an online magazine, please send it this way… This is the mag we’re producing for the OSS community –> http://mag.my-opensource.org
July 11th, 2009 at 12:13 am
one more nice topic in your blog and nice comments too keep it up, by the way Graz is a very lovely city I enjoyed it so much