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?

6 Responses to “Where is the documentation?”

  1. Chris Smith Says:

    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

  2. Dang’s Weblog » Documentation redux Says:

    [...] 6/16/2005 Documentation redux Filed under: Gentoo — Daniel @ 10:42 am Daniel I think you’re missing a couple of things. First, [...]

  3. mika Says:

    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.

  4. dsd’s weblog » Blog Archive » Documentation again Says:

    [...] dsd’s weblog throw the sailors overboard « Where is the documentation? Documentation again [...]

  5. lotso Says:

    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

  6. Hareedy Graz Says:

    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

Leave a Reply

You must be logged in to post a comment.