Documentation Strategies?

An anonymous reader asks: "I'm a developer and have been given a task of creating documentation, for fellow developers, on how the system (a CMS) I have implemented, and adapted, works and how to develop for it. On the surface it doesn't seem too complicated but the amount of information I need to get down on paper, and the level of detail needed on some parts, is great. What's the best way to approach this task when there's so much information bouncing about in your head you don't know where to start?"

Comments

Outline, outline, outline

[Saanvik]

Look, you don't have a lot of time, and you don't have a lot of experience documenting software (you're a programmer, right?), so you need to use writing tools, rather than instinct, to maximize the result of your effort.

The best tool you can use is an outline.

Make sure you start with a document purpose (the more detailed the better), then organize your information in goals and tasks.

For example

Purpose: Use CMS to manage information throughout its lifespan.

Audience: Developers that are forced to write documentation

I. Overview
An overview of the system

A. Why should you use CMS
i. You won't have to write as much
ii. Those damn writers will leave you alone ....
v.

B. CMS process [result of a work flow model]
i. [intros to major sections II - XXX] ....
xi.

II. Creating a set of documents

III. Creating a single document

IV. Finding a document

V. Deleting a document

VI. Versioning a document

etc.

There are a lot of other tools you can use (3x5 cards, doc plans, work flow models, etc.). Just make sure before you write one word you outline your document. Otherwise it won't work well, and you, or the person that takes your job when you've failed, will have to re-do it.

Besides helping you scope out the work, once you have an outline it's easy to fill in the blanks with paragraphs because you know how to do each of the sections in the outline. For example, I'm sure you know exactly how to delete a document from your CMS system. So, when you get to that item in the outline, you don't have to think, you just write.

Go top down

[Jerf]

Designing from the top down is generally a disaster. But for an existing system, it is the best way to document it.

Few people document, even fewer do it well. One of the great crimes people commit against their fellow developers is to not give the bird's-eye view. If you want details, you can always go consult the source code. Getting the bird's eye view of the system, the unifying vision, the overall-architecture, that is much harder to extract from the raw code.

Draw the system out on a sheet of paper at a high level, the interacting concepts and major architectural features, the fundamental metaphors. These things need not literally exist in the code. That's your first diagram in the manual. The first chapter is a couple of paragraph overview of each blob, and a description of how they conceptually relate in the system.

Next, figure out some good order to drill down into the blobs, expanding them out as necessary and trying to minimize the pre-requisite knowlege necessary for each blob. As you drill down, you'll find you forgot high-level abstractions in the first chapter, and you may even find yourself eliminating some you thought were high level. (Few things refines your own understanding of a system like documenting it!) Document with a progressively-higher-detail "spiral" until you reach a reasonable level, such that there's no poing documenting any more since it would be faster to consult the code.

You are allowed to assume some domain knowlege, and the willingness to actually read the docs. (Without either of those two you're hosed; you can't teach the entire domain in a manual and you're not writing for people who won't read the docs, you're writing for those who will.)

Advantages:

• Gives view of the program no amount of source reading can
• Less reading leaves the user more capable of doing things in the system then a raw API table, shorn of context
• You start off from day one with a usable, albiet incomplete document, whereas an API document will most likely be useless without understanding the rest of the system. (In theory, your system has isolated concerns and it is not necessary to understand the whole to understand part. In reality...) You can stop at any time and still have a valuable document.
• The system itself will guide you towards what needs to be documented; you'll see what I mean as you get into this.
• You may discover a new and wonderful design for the system, which even if you never get a chance to implement it may educate you enough to make this whole thing worthwhile.

I actually tend to enjoy writing docs, for the reasons above.

API references are necessary, eventually, but in a way, they are the least important thing you can pass on, not the most. As the old saying goes, "Give me your code, and I will not understand your data structures. Give me your data, and I won't need the code, it will be obvious." Similarly, "Give me your API, I won't understand the concepts. Give me your design, and I almost won't need the API; it will be obvious."

I have written the documentation .

[snester]

Our software www.viewbuild.com to me did not seem complex at all especially since i'd used it was being developed.

My first manual - 100 pages attempted to simply document the features - me figuring that everyone would understand the way the software was written and what was expected of the user. Bad mistake #1 - no one got any use out of it - except me who used it to learn.

My second manual 160 pages then attempted to document everything but show examples of the tools in action. The only people who understood it were trainers and some coders.

My third manual 216 pages was outsourced to a professional trainer. The problem was that it had to be done as 1 hour lessons - you couldn't just go to the index to find out how to build a two storey house. It was good for training sessions only, the general public found it particulary confusing.

My Fourth Manual 350 pages was a complete re-think after examining other manuals more closely. It was focussed on what people kept asking. How do I do this - How do I do that....In essence it was a description of the software and an indexed FAQ.

Another thing to consider is how the manual is put together. People loved my Ring Bounded Manual - because the pages sat flat. Unfortunately it did not look very professional so i experimentended and ended up with a landscape A5 perfect-bound format. As a final word - you are better leaving 3/4 of a blank page than running into a new chapter to save pages.

regards