• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Release It!: documentation of software

 
Gian Franco
blacksmith
Ranch Hand
Posts: 979
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hello,

What would you consider the next best documentation
practices after self-documenting code?

Kind regards,

Gian
 
Michael Nygard
author
Ranch Hand
Posts: 40
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Gian,

I'm definitely of the agile school, so I don't believe in creating documentation of no value.

Now, sometimes that gets over-interpreted into saying "no documentation". I couldn't agree less with that approach.

Most of the time, systems will be operated by people other than the ones that built them. When you're all on the development team, it's easy to collectively share the knowledge that "Maximum entropy exceeded, channel needs reset" is just there for developers to be clued in about how often a cryptographically secure channel exhausts the number of "safe bits" it can send.

On the other hand, people in operations can easily see that and think: "Oh my god! I need to restart the server."

So, we do need some documentation to transfer that knowledge about vital runtime behavior from the dev team to operations.

So, what form should that documentation take? Exhaustive lists of error messages seem difficult to produce, but modern IDEs give us some tricks we can use. (Hint: it has to do with externalizing strings for I18N.) Still, I regard a catalog of error messages as something of a last resort.

My favorite type of documentation is what I call a mini-doc. This is a one- or two-page description of some "interesting" (read: "could surprise you later") behavior. In a wiki, these enable just-in-time learning and continuous improvement of the documentation itself.

Cheers,
-Mike
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I think we have to distinguish between two audiences of documentation.

For those people who will have to maintain the system (preferably a subset of those people who build it), the next best thing - no, I'd actually say an even more important thing that self-documenting code, is an extensive suite of acceptance tests. They tell you how the system is supposed to behave, and even when you changed something that broke that behaviour.

For the actual users of the system, I'd say the most important thing is an intuitive UI with meaningful messages. I agree with Mike that a mini-doc is a good thing, although I'm not sure we should build systems that actually have "interesting" behaviour...
 
Michael Nygard
author
Ranch Hand
Posts: 40
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Ilja,

For any server-based system, such as web sites, there is a third constituency which is the people who run the servers and the applications on the servers.

I am particularly interested in how to provide them with useful information. These are usually system administrators who have (reluctantly) been pressed into service supporting WebSphere, .NET, Apache, etc. By and large, they do not come from development backgrounds and are usually not involved in the design and construction of the software.

These folks, who have the least information about your system, are the most critical to its continued operation.

(As an aside, these are also a group that is unlikely to just sit down and read documents. They'll reach for a run book when there's a problem.)

This is where I have gotten good results with the mini-doc format, especially when they can be searched and found rapidly.

Putting the minidocs in a wiki format also allows the operators to provide information back to development. You might be surprised what they learn about how your system behaves. You might also be surprised at what kind of superstitions Operations can develop. Closing the communications loop here helps everyone.

Cheers,
-Mike
 
Zsuzsa Nagy
Greenhorn
Posts: 3
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi!
I wonder if you guys have any good practices/tips to share about gathering feedback from the users/customers on the documentation if the sw is developed in short cycles - and the documentation might be lagging behind anyway... Is it part of the general get-feedback-of-the-user channels? Is in your experience added value in actively gathering information from the users specifically on the documentation?
Thanks!
Zsuzsa
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Zsuzsa Nagy:
the documentation might be lagging behind anyway...


The best thing is to not let that happen. Why would you want to? http://www.xprogramming.com/xpmag/Ferlazzo.htm

Is it part of the general get-feedback-of-the-user channels? Is in your experience added value in actively gathering information from the users specifically on the documentation?


In my opinion, it doesn't make much sense to separate the feedback about the documentation from that about the rest of the product. The best documentation is the one you don't need, because the system is so dead simple to use...

So I'd rather gather general information on how easy the users find the system to use, and what typical problems they encounter. When we identify something that could be improved, I'd first look at how we can improve the software so that it is easier to use and understand by the user - and only if that doesn't suffice see how to provide better documentation.

So, for example, if we get a support request with an error message the user doesn't know how to react to, we first analyze on how to remove the possibility of the error to occur at all. The next step failing that is improving the way the error - and advice on what to do about it - is presented to the user. Only then we look at the documentation - after all, most users don't look at the documentation, either...
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic