Software Documentation

August 27, 2007 8:24 AM

I am a technical writer looking to improve my company's software manuals. I want to stay up to date with the latest technology documentation trends. Please leave comments on what you think some of the best manuals are for different software products and why. Basically, if you’ve ever read a software user manual and thought, “Wow! That was surprisingly easy to read…or helpful…or well organized…etc., then that is what we are looking for.
posted by JPowers to technology (12 comments total)

Subversion (source control) documentation. Well written and well organized.
posted by syzygy at 8:27 AM on August 27, 2007

The Mac bible, 4th Ed, is my favourite-ever piece of software writing. I still remember tips from it, but I suspect that's more down to Arthur Naiman's style than anything else.
posted by bonaldi at 9:17 AM on August 27, 2007

No specific suggestions for manuals, but in general it seems that software and its documentation are written by software geeks. Okay, I realize this is necessary, but when doing user interfaces (both for using the software on the computer and in the documentation) it should be the users that have the greatest say.

In other words, it should be with the knowledge of a programmer, but in terms that a layman, non-programmer can understand. When writing out technical instructions, I try to assume that I won't be there to explain it to the person reading them, and that they won't have anyone around to ask questions. I imagine that I'm writing the instructions to my mother, or to my son, and they won't be reading them for a couple years. That way, I include all the information to answer any questions they may have.

I'm not a professional tech writer, but writing detailed procedural instructions is part of my job and also something I do as a hobby (on automotive forums).
posted by Doohickie at 10:29 AM on August 27, 2007

Thanks for the responses. Here's something else to think about. What do you expect when you buy software ... a big, ugly user guide with everything you ever need to do (that replicates help files and is tough to dip into and navigate)? a quick, slick getting started and basic concepts guide? both?
posted by JPowers at 10:29 AM on August 27, 2007

I expect to not have to read anything, at all. Computer Games are a good guide here -- they used to have doorstop manuals, now they teach you in-game: "Hey, here's the sword! If you press A you can disembowel Hogwarts pupils" etc.

With hardware I have more tolerance for reading, but not much.
posted by bonaldi at 10:39 AM on August 27, 2007

Quick-start manuals are about as much as I want to read. If it's going to take more than that, I'd rather participate in a hands-on tutorial, pretty much what bonaldi said.
posted by misha at 11:08 AM on August 27, 2007

I have several books myself ... personally I hate anything on paper these days. Most docs suffer from too much blabla and not enough "How do I do this or that" information. Most manuals (electronic and print) lack got indexes and keywords.

Illustrations and images - most manuals talk to much and show too little. I always like good videos and presentations.
posted by homodigitalis at 11:19 AM on August 27, 2007

What kind of software? For home, business, or techie use? The documentation requirements for iTunes, Excel, and Oracle, e.g., are wildly different.
posted by magicbus at 12:18 PM on August 27, 2007

I agree with bonaldi; I expect only to use manuals for reference if I'm trying to do something complicated, otherwise I should get help as I go along and maybe, if it's absolutely unavoidable, a quick start guide. A non-computer game app that does a really good job of guiding the user is TechSmith's SnagIt.
posted by phoenixy at 12:29 PM on August 27, 2007

The software is for a business.
posted by JPowers at 1:02 PM on August 27, 2007

A max 3 page quickstart guide is always helpful. Workflows for common tasks are also helpful, with links for doing "other" things that may be more complicated (ie, "click the X button to do Y automatically (or click here for doing Y manually)").

I really, really dug the Shake manuals. I'm guessing they've been cleaned up, but they were honestly entertaining to read through, and you really got a good view into how the developers themselves used the software.
posted by devilsbrigade at 2:32 PM on August 27, 2007

Sorry for not directly answering your question, but based on your follow-up question I think asking "a bunch of strangers on the internet" what makes your company's doco great isn't the right people to ask.

The first step would be trying to find out what the people actually using your software are looking for.

If you can't get direct access to them, talk to your colleagues providing customer support or the BAs who go on site to gather requirements, or the people implementing the system, or if all else fails the people selling the software.

Also think carefully about who your audience is aside from those end users. There's, again, customer support, the implementation, sales people and everyone else within the company who may also rely heavily on your documentation (depending on how mature the organisation is, your documentation may be the only doco around if there's no specs, requirements documentation etc.)

There's a world of difference between the best-selling Dummies books or the groovy Head First series -- both of which can be stylistically very appealing -- and the cold, hard-nosed reality of user documentation for enterprise systems.

I like to think I know what I or my peers think great documentation is, but that's not necessarily what meets the needs of the people actually using the software for which we provide the documentation, nor what our employers are paying us for. There's always a trade-off between my anally retentive need for perfection and my company's need to maximise profit.

Also keep in mind that sometimes users don't know what it is they actually want* so bring your tech writer skills to bear to provide the information required in the most appropriate format.

* people really want software that's so great they don't need doco. So sometimes rather than adding another section to your online help or user guide, try talking the developer into using your error message text rather than the standard uninformative goobledygook.
posted by l'esprit d'escalier at 3:35 AM on August 28, 2007