File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Agile and Other Processes and the fly likes Release It!: documentation of software Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Android Security Essentials Live Lessons this week in the Android forum!
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "Release It!: documentation of software" Watch "Release It!: documentation of software" New topic
Author

Release It!: documentation of software

Gian Franco
blacksmith
Ranch Hand

Joined: Dec 16, 2003
Posts: 977
Hello,

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

Kind regards,

Gian


"Eppur si muove!"
Michael Nygard
author
Ranch Hand

Joined: Jan 03, 2007
Posts: 40
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


Michael T. Nygard<br /><a href="http://www.michaelnygard.com/" target="_blank" rel="nofollow">http://www.michaelnygard.com/</a><br /> <br />Release It! Design and Deploy Production Ready Software<br /><a href="http://pragmaticprogrammer.com/titles/mnee/index.html" target="_blank" rel="nofollow">http://pragmaticprogrammer.com/titles/mnee/index.html</a>
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
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...


The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Michael Nygard
author
Ranch Hand

Joined: Jan 03, 2007
Posts: 40
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

Joined: Sep 08, 2006
Posts: 3
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

Joined: Jul 11, 2001
Posts: 14112
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...
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Release It!: documentation of software
 
Similar Threads
Standalone JPA example
Ajax tags problem
activex
setting multiple struts-config
Project Tru-isms