Slashdot Mirror
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?"
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
A shrubbery