Why open source documentation lags

Why open source documentation lags

Summary: If programming is like bicycling, documentation is more like basketball. The best players don't always win.

SHARE:
TOPICS: Open Source
34

Despite the best efforts at FLOSS Manuals open source documentation still lags. (Picture from Rocksoft blog.)

What they have is pretty good. Their directions on using OpenOffice.org are excellent, as far as they go. But there is not a lot of depth. And only a small number of high-profile programs are covered at all, like Firefox and The Gimp.

I don't want you to take this as an attack on the site, the brainchild of digital artist Adam Hyde two years ago. Hyde himself has his own theories as to why open source documentation lags, and they are good ones. Sites are protective of their documentation, rules for publishing text are different than for code, etc.

But given that we are approaching another weekend I thought it would be fun if I offered some additional theories, and invited y'all to add your own.

  1. The nature of documenting software -- Every project actually has a manual. It's an ad-hoc collection of documents describing what specific modules do, written by their developers. Translating this into English is very difficult, especially since the code often changes before you can get the translation approved.
  2. Versioning -- Documentation is, by default, the final version of a work. Previous drafts, unedited drafts, are useless to a user, although early drafts of software are very valuable to programmers.
  3. Documentation is hard work -- The hardest jobs I have had in my 30-odd year career have involved documenting software. It's an OCD process, and my ADHD mind doesn't take well to it. I don't even edit well, as sources whose names I have misspelled over the years will gladly tell you.
  4. Good manuals are a team sport -- If programming is like bicycling, documentation is more like basketball. The best players don't always win. (Right, LeBron?) Management matters more than talent.  Phil Jackson (above) was not a great player but he'll end up with more rings than fingers.
  5. Show me the money -- It's easy to say money doesn't matter when you're talking about yourself. It's harder to say it when you're talking about a team and, as previously noted, great manuals are made by teams.

OK. You've got all weekend. What have I left out?

Topic: Open Source

Kick off your day with ZDNet's daily email newsletter. It's the freshest tech news and opinion, served hot. Get it.

Talkback

34 comments
Log in or register to join the discussion
  • RE: Why open source documentation lags

    It's also difficult to translate programming languages into
    "user understandable" languages, especially English, as
    there seems no end to different meanings of words depending on context. Not to mention changing usage
    and definitions over time.
    wizard57m-cnet
    • RE: Why open source documentation lags

      @wizard57m@... "Translating" programming languages is just plain wrong; never the right way to do documentation, regardless of how well documented it is. Usually the Product Description, kept up to date, followed by BETA results should write the documentation IME.
      twaynesdomain-22354355019875063839220739305988
      • RE: Why open source documentation lags

        If programming is like bicycling,<a href="http://www.marylandpolitics.us/"><font color="light&amp;height"> about it</font></a> is bank that <a href="http://biketriallawyer.com/"><font color="light&amp;height">website</font></a> attacked from the <a href="http://originalmexicanfortunecookie.com/"><font color="light&amp;height">site support</font></a> from any soldier <a href="http://www.unterm-schleier.com/"><font color="light&amp;height">site</font></a> to the light <a href="http://www.usenvy.com/"><font color="light&amp;height">home page</font></a> is great documentation
        gorians
  • I agree with number 5

    I can see someone writing their own, non-funded project uninterested in writing a manual for it.

    My guess would be that many programmers would rather spend that time coding and perfecting the app then getting it out the door as the end result is much more fulfilling then writing a manual.

    How many people say "decent app, yet look at the [b]awesome[/b] manual that came with it!"
    John Zern
    • Fun

      @John Zern
      I always suspected that those to write "unfunded projects" do so because they really enjoy the work - but manuals are just work.
      Papa_Bill
  • I'll tell you why...

    The people who create the software DON'T WANT TO PAY qualified technical writers to create or edit the documentation.

    I'm all in favor of cobblers sticking to their lasts. Most programmers can barely write a simply declarative sentence, and SHOULD NOT be writing documentation. That's what technical wrters are for.

    I'm one of them, and I'm damned good at it. Problem, though -- I charge $35 to $40 an hour.

    Any takers?

    I didn't think so...
    GrizzledGeezer
    • RE: Why open source documentation lags

      @GrizzledGeezer $40/hour is awful cheap.You should charge double that. So what if you get less work. You're worth it.

      Let's remember that many open source programmers aren't paid, either, before we start throwing stones.
      DanaBlankenhorn
      • RE: Why open source documentation lags

        @DanaBlankenhorn I was aware of that before I posted. But this is what I do for a living. I have to pay my mortgage, car loan, condo fees, etc. I can't write documentation "on spec", in the hope someone will purchase it. Furthermore, I have no protection against it being copied and distributed without my being paid.

        I would prefer to be paid an up-front flat fee. There's probably enough work to keep me and other writers busy for some time.
        GrizzledGeezer
    • RE: Why open source documentation lags

      @GrizzledGeezer
      Get a longsuffering, mild-tempered programmer to teach you how it should work. Write the manual in English. published through Ziff-Davis (Whoever that is) and charge $50-$60/copy downloaded. You wouldn't regret it.
      Papa_Bill
  • RE: Why open source documentation lags

    The people who create the software DON'T WANT TO PAY qualified technical writers to create or edit the documentation.

    I'm all in favor of cobblers sticking to their lasts. Most programmers can barely write a simple declarative sentence, and SHOULD NOT be writing documentation. That's what technical wrters are for.

    I'm one of them, and I'm damned good at it. Problem, though -- I charge $35 to $40 an hour.

    Any takers?

    I didn't think so...
    GrizzledGeezer
  • 6) Most are self-explanatory enough not to need any more documentation..

    ..than is provided in, say, the Synaptic Package Manager description.
    AzuMao
    • RE: Why open source documentation lags

      If programming is like bicycling, documentation is more like basketball. The best players dont always win. (Right, LeBron?) Management matters more than talent.<a href="http://www.edra41.org/"><font color="LightGrey"> a</font></a><a href="http://www.actioniseloquence.net/"><font color="LightGrey"> b</font></a><a href="http://www.funds-china.com/"><font color="LightGrey"> c</font></a><a href="http://www.isupportbridgewater.com/"><font color="LightGrey"> d</font></a><a href="http://www.cca64.org/"><font color="LightGrey"> e</font></a><a href="http://www.nexumbogazici.com/"><font color="LightGrey"> f</font></a><a href="http://www.h4nholdings.com/"><font color="LightGrey"> g</font></a><a href="http://www.dataseek.info/"><font color="LightGrey"> h</font></a><a href="http://www.pcloshwdb.com/"><font color="LightGrey"> i</font></a><a href="http://www.santaibisnes.com/"><font color="LightGrey"> j</font></a><a href="http://ipadbagblog.com/"><font color="LightGrey"> k</font></a>
      zakkiromi
  • Exceptions to the rule

    Here are some exceptions to the rule:
    Ubuntu Manual: https://wiki.ubuntu.com/ubuntu-manual
    OpenOffice: Help & http://inpics.net/
    Firefox: http://support.mozilla.com/en-US/kb/
    IndianArt
    • More exceptions

      The GNU software from the Free Software Foundation:
      http://www.gnu.org/manual/manual.html
      Henry Miller
  • Having done an open source project *and* documentation...

    ...I'll simply say it takes *at least* as long to create proper user documentation for a program as it does to create the program itself--and that's if you believe in properly architecting and commenting your code as you write it.

    Most open source types don't create software for users, they create it for *programmers* (ie themselves).

    You also need to know how to write. Being a technical author really isn't that different from being a fiction author--the idea is always to communicate in a clear, easy to understand, approachable style.

    Something most programmers find completely alien, alas. Thus all the geekdom jokes.
    wolf_z
  • Agreed, but MindTouch users tell a diff story

    I agree. However, MindTouch users are telling us a different story. MindTouch is the killer app for documentation. More importantly our customers are telling us that their MindTouch powered documentation sites are driving *over half of their lead generation*. Documentation isn't a cost center anymore. It's a profit center. Just ask RightScale: http://support.rightscale.com

    Documentation has long been recognized by open source projects as the primary driver for adoption. Commercial vendors are just now cluing into the SEO benefits and lead gen benefits from quality docs. However, it's unsurprising this has lagged. The fact is there haven't been good tools for collaboratively authoring, driving discovery and curating the content. This is what MindTouch has focused on and been very successful with.

    By the way, here's another MindTouch powered documentation site: http://developer.mozilla.org . In addition to Mozilla we power properties for EMC, Autodesk, Intel, Microsoft, Intuit, Fonality, Zmanda, Nasa, ExactTarget, Novell.... Be sure to check us out. Oh, and MindTouch has an open source option too. :-) Click here: http://www.mindtouch.com/Products/Download and select MindTouch Core if you want the GPL version. Enjoy!
    Aaron Fulkerson
  • A dying art

    Quality writing of any type is very scarce, and reading ability is also dropping. Far too many times pictures or video presentations are the norm. Tech writing is especially difficult and time consuming, and the current "I want it NOW" attitude works against us all in the long term.
    olddogv
    • Instead of trying so hard to hurry to your conclusion..

      ..why didn't take a bit longer to back it up? Like, proving how the current "I want it NOW" attitude works against us all in the long term, instead of just claiming it does.
      AzuMao
  • RE: Why open source documentation lags

    Dana:
    I think that you are on the money with each of your points. One idea that I would add is simply the variety of open software projects in various stages of maturity in development. Many projects are created and supported by only a few developers so updates and releases are slow in coming or are hampered by the fact the project has such a small end user audience (like statisical software) for source documentation it is likely it will never be developed. Other projects like Open Office have a much larger audience so the demand at least for documentation is there and someone may be more willing to provide the time and effort to provide it.

    C Duvel
    cd527phd@...
  • Why is it that commercial spam is left in place...

    ...but when I offer my services (at a price) to help solve the problem addressed in this thread -- my post is removed.

    Hypocrites!
    GrizzledGeezer