What development documentation do you find useful

Question

I find that for most software projects, documentation is often oriented towards the process of development the software, rather than supporting and maintaining it. This is particularly true when using agile methodologies, which emphasize minimalistic documentation.

The issue with development-oriented documentation is that it tends to be less usable as a reference, especially after a few releases. It's a pain to sifting through a pile of story cards (or story pages on a wiki, as our team uses) trying to work out which stories are current, and which have been modified (directly or indirectly) by more recent stories. A full waterfall-style requirements specification, technical-design document, etc. may be fine if development is always done in a big bang, but as bugs are fixed, minor features added, etc. it may be difficult to maintain.

I'm a fan of minimalistic documentation, as the less documentation there is, the easier it is to find things (assuming what you're looking for is documented, of course), and the easier it is to maintain.

I am thinking of extending our wiki-based story pages to contain some meta-data, i.e. references to other stories which are related, affected, obsoleted, etc., similar to IETF RFPs.

I'm interested in hearing about other peoples' experiences with lightweight approaches to software documentation that works for maintenance and support, not just delivering a project and tossing it over the wall.

Update: I don't consider class-level documentation to be enough, whether using inline documentation such as javadoc or unit tests as documentation. These are fine for developers, but testers, support staff, trainers and the like need a way to understand what the expected behavior of the code is. This needs a higher level view of functionality than class-by-class. Each class may be doing what it was meant to do, but is how is the component as a whole supposed to work? This is why I personally favor the user story as a basic unit of documentation.

Answer 1

I'm a big fan of samples which show how to use the generated classes; usually the unit tests do a good job, but they can be hard to sift through on large projects.

Answer 2

There are several levels of software design visualization. For simple projects you might only need to keep and maintain Low Level Design documentation, perhaps a page or three per module.

For larger projects you really need a hierarchy of information - from a 50,000 foot overview, to high level documentation on larger parts, to low level documentation for each implemented module.

No single, simple documentation system is going to be a good 'catch all' for all projects, those who try to shoehorn this system into every project may be doing more damage than helping.

Assuming your projects are generally medium to small (ie, implemented in less than 6 months with a team of fewer than 3) then a very simple Wiki system with copious links should suffice. Spend a lot of time defining common terms, and when someone adopts a phrase make certain it is used project wide. This will enable searching across the wiki for all places Module_Foo_Baz is called, implemented, abused, tested, documented, approved, etc.

Answer 3

I find generated documentation (e.g. JavaDoc) to be very effective, so long as it is actively maintained. It's too easy to stop updating the inline documentation once the initial APIs are stabilized, but it is crucial if the documentation is to be usable for maintenance down the road.

I too use a Wiki to keep track of project information; where the JavaDoc houses API documentation, the Wiki keeps track of development methodology, build and install notes, dependencies and requirements, product testing information, database schema changes, and the like. We use Trac for managing this information, which I've found to be a huge help.

Answer 4

I'm partial to gotapi.com. It combines several online docs and gives the kind of auto-complete search which is invaluable if you're not certain of function or method names. Some of the supported documentation is of lesser quality, but the system is open and new and better docs can be added over time.

Answer 5

I'm not a huge fan of documentation, which I've found can quickly get out of date. I think unit tests work as fantastic documentation and is my first port of call when I'm starting to learn a new API.

Answer 6

With respect to long-term usefulness, comprehensive and updated comments within the actual code would top my list. Most other forms of UML-based documentation (class diagrams, flow charts, use case diagrams etc.) and feature lists, while useful and important, tend to satisfy management and marketing ideals rather than purely enhance code development and maintenance goals.

Any structured and comprehensible document that can be dynamically (on-the-fly) derived from inline commenting would be welcome.

Answer 7

In my expierence, I have found documenting the functional requirements and then design intent is useful. As the project evolves it is paramount to keep the functional requirements up todate, not so much the design documents(although if these are minimal then it is also useful to have as an overview for how the code is structure and behaves) As the code matures and is a full body of work, it should now describe how it is working. Again a top level overview (that is up todate) is useful for explaining to the new guy how the system and its elements all work together, but the detailed algorithm for a specific function will always be in the code (how it is actaully working).

The design documentation should describe two major things; the data/code structure and the behavior, and a picture is worth a 1000 words. We have been using UML like diagrams to help provide this form of documentation.

Answer 8

My favorite form of documentation is more applicable to scripts than to large OO projects, but can be used either way.

Simply put, a change record at the top of a class / script that has a numeric reference number. For instance

4056 - Steve K - Changed this procedure to reflect description of problem
4057 - Mike L - Changed the way this is handled because of and so on

and then anywhere code is changed, include more specific comments pertaining to the particular function / code, including the numeric ID, so that searching through the code reveals everything changed that was part of the same solution.

Answer 9

I will take any docs that I can get my grubby hands on. I also try to snarf up the spec and take a look at the tests. If there is no spec, how does the dev team know whether it produced the appropriate code? If no test suite, how does the dev team know whether it produced the correct code?

I really like JavaDoc-ish docs. Everyone knows the problem with these is 1) getting devs to write them in the first place and 2) getting devs to update them when they change the code. I see no reason that devs should be let off the hook, no more than they should be updating their unit tests as well. Both are crucial to the success of a project. Both should be discussed during code reviews, triages, annual reviews. No one can be said to be a good developer who neither updates their comments nor updates their unit tests. If you permit the shop-worn excuse "I didn't have the time" either the project management has no interest in quality (and is likely only date-driven so you should find another gig), or is gutless (and will never stand up for you if anything hits the fan).

The whole purpose of docs is to SAVE TIME. I can create my own class diagram by using Reflector or something like that. There is no reason dev docs do not keep an up-to-date version based on the latest release using reflection.

Online docs are the way to go. Assign each newby to go through them as they get up to speed.

And PS, if you want world-class docs, hire a world-class writer and give them support. In my 20 years of programmer-writer contracting I've seen a lot of lip service given to docs, but rarely seen a lot of support. Most see docs as an expense, not an opportunity.

Docs are hierarchical. First you create the ref docs. Think of these as the foundation. Without this level, the rest is worthless. Next comes the guide, the "Using" or "How-to". Here you pick out the top 8/10/12 most common scenarios and describe how to do them. Next, a tutorial where you walk the reader through creating a "reasonable" sample. Step-by-step, with code that works for each step. This doc must be constantly updated as each release hits the street.