How do you approach documentation (external, not in-code documentation)?

Question

What are some practices for documenting your system? We work with a 10-year-old system where there is no requirement for documentation. That includes business analyst requirement documents or technical documents. Right now, everything is put in one Word document and stored on a remote server. But no one really reads the documents after a project is over. But there is relevant information there.

What is your strategy for describing your app? Do you have any hard rules?

We are considering using a wiki (MediaWiki) and also using Bugzilla for issues and some documenting of code.

Is SharePoint a useful task for this?

Answer 1

Personally I use Tiddlywiki and Dia.

But some other great ways of doing that are to use a generator inside the code which takes your comments and turns them into external documentation (like JavaDoc).

What I'd really like to see is something like JavaDoc (a doclet) that outputs a Tiddlywiki!

(Wouldn't hurt if it output a couple of Dia diagrams as well, but that's probably too far flung...)

There are also Server-side versions of Tiddlywiki, which is great because you can download an online version work on it, and upload the changes back up to the server again if you are coding off-line.

Answer 2

What i've done in the past with these sort of projects is rather then try and document in detail, do the following:

• create one or two high level diagrams
• upload these to a wiki, and link to any other documentation that exists
• create a section for troubleshooting, or known workarounds
• create a list of bugs
• create a list of enhancements

And off you go.

This gives people a one stop shop of what is going on in a project, and how to resolve any current issues.

I would think Sharepoint is too complicated for this, although you could use sharepoint to do it.
MediaWiki is easily good enough for this.

Answer 3

Focus on describing the large-scale whys, not the nitty-gritty hows, unless they are really unexpected or complex. Capture the business benefits which are important to system stakeholders, and the major nonfunctional requirements which are expected of it. This is the kind of documentation that helps keep a system from veering off mission (and which every new developer needs).

Capture the external and internal interfaces between components and between the system and its environment. Try to be very clear about preconditions and postconditions. These interface specifications help you evolve the components separately, and allow you to work with simpler elements.

Prioritize documenting any base classes or commonly used data types. Always document the physical data model used (capture diagrams at least, but try to supplement them with textual explanations for those who aren't visually oriented).

Prefer subdividing the documentation rather than having the One Design Documentation. Such documents grow too large, are always out of date, and are scary to modify. With several smaller documents more people dare write down what they have learned, in parallel. A wiki can work quite well, especially if you organize some top level entry points and make sure that history is kept.

Answer 4

Quietly enough not to disturb, but not so quiet as to surprise, whilst holding out offerings of caffeine and chocolate...

Oh, that's not what you meant, is it?

You wrote that there's "no requirement for documentation", so I'm not sure what problem you're trying to solve. Do you personally feel obliged to document, or do you think there should be a requirement for documentation, even if it hasn't been made explicit? Is your system Web-based, desktop-based, or otherwise? If it's Web-based, I'd certainly go with the MediaWiki approach as something familiar enough for both developers and users. I might recommend that for desktop-based systems too, especially if there's a feasible way to integrate links to the Wiki into the desktop environment.

Answer 5

At my company, we started using a MediaWiki installation about 6 months ago -- it's finally gotten to the point where you can find what you're looking for about 50% of the time. It's a nice system because it is stupid simple to use, which means that more people will be willing to contribute. There are almost no standards on HOW to document; our company has the viewpoint that enforcing hard standards will simply defer people from writing ANY documentation. Poor documentation is better than no documentation. There's a team of editors that specifically worries about quality control, and since it's a wiki, anyone in the company can take the time to make some poor documentation better.

The real tough part of implementing any documentation system in your company is not going to be the technology, though. It is going to be buy-in. People will initially think of documentation as a waste of their time, which means that people won't want to contribute, which means that people won't want to use the documentation source (as it will never contain what they need). Depending on the size of your organization, getting up that hill will be tough.

We have one employee around here who almost religiously believes in the power of documentation. He has held dozens of classes, sent out many emails, and had hallway conversations with people to make the pitch to document. His angle? "Documentation will save you time, because people will stop bugging you over and over again with the same ten questions." The evangelizing has seemed to work out well. If you're really interested in people documenting their work, that might be the way to sell it to them.

Answer 6

My group has two major documentation systems and it seems to work well.

First, we have a wiki, where the product managers describe new enhancements and features, post screenshots, etc. I use those pages to figure out what to write, and QA uses them to figure out what's a bug.

We also use Trac. QA enters bugs and the PMs enter enhancements as Trac tickets. It's tied into svn, so there's a page for every commit. Each ticket is linked to the checkin that fixed it (determined automatically via parsing the svn commit comments) and each checkin page has a file diff, so it's pretty easy to search for a problem and see how it was fixed.

We actually have a couple of other development groups working on products that share our database but not our code. They each track their bugs and commits separately (in their own Trac installs). We share the wiki, though, because those pages specify the interfaces between products.

And that's about all the documentation we do. The codebase, though huge, is largely self-documenting, and if not, grep is your friend. :)