Fog Creek Software
Discussion Board

Technical Documentation

I'm looking for examples of good technical documentation. I'm looking for format and content - What should technical documentation include?

Friday, August 22, 2003

What kind of documentation? I would suggest that you look for comparable products and see what they did. Go to the book store. If you are doing open source software look at what other projects are producing. There is no one right answer. That is the nature of design--fitness.

You might look in the archives of TECHWR-L. Google it.

David Locke
Friday, August 22, 2003

If you could be more specific then it would help.

If you are looking for something that documents your code or an API then there are some automated tools that will help you.

In the .NET world you have NDoc which generates MSDN-style documentation from .NET assemblies. It can be called from Nant to gen docs when the system is built. Very snazzy.

I'm sure Java has a ton of similiar tools as well.

Mark Hoffman
Friday, August 22, 2003

I am familiar with NDoc and we are currently using this.  I'm looking more for examples of documentation like... input/output, copybooks, database ERD documents, flowcharts, OO design documentation, documentation that describes a program or system without it literally being code snipits.

Friday, August 22, 2003

I'd call ERDs and informal, lingua franca UML diagrams (for OO design) the most worthwhile of any of that.  And I'd only consider UML diagrams useful in terms of A) the design process as it happens, for a look at the history of a thing, and B) a sketch of a finished and rarely-changed system.

Anything less useful quickly goes out of date and becomes confusing.  The overview level is quick to write and useful to read, the low level is the code, and the medium level has very limited audience for the amount of work required.  I mean, the goal of this sort of technical documentation is documenting for (current/future) programmers, and personally, I'd rather read the code than read code plus associated explanation of how it was at one time that purports to still be correct but isn't.  This is useful at the overview level, to give context to design decisions, to understand the major design eras and their whys and wherefores.  At the medium level you get a lot of "This function has three in parameters" -- which tells me nothing about why the fourth was added, or which of the three was removed, or why no one seems to use this function any more.

Hmm.  So, as for good tools, I use a whiteboard/napkin for sketches, then Visio for sketches I want to keep for a while.  Good examples, what it really comes down to is the minimal amount necessary to communicate with the people in the group.  This means if I showed you mine, they'd make little to no sense, because they're culturally relative.  Basically, if the entire development branch here got hit by a bus on the way back from lunch and you had to take over for me, they'd be almost useless; but, the company would be in much worse trouble at that point, and the risk is fairly small.  So enough for me to understand myself later, and enough for my coworkers to understand me now and in my possible absence later...but no more.

Tuesday, August 26, 2003

*  Recent Topics

*  Fog Creek Home