Dana Blankenhorn has been a journalist, writer and part-time futurist for over 30 years.
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.
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.
- 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.
- 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.
- 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.
- 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.
- 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?
Click here: 
