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?"
There are 3 things people are going to want to know:
Methodology
Process
Technology
If you can answer those 3 things in detail, you've got your documentation started.
Make it look however you want to look. Summaries are nice.
TOC are really handy.
Add images only if a picture will save you 1000 words.
Don't BS or say what you think they want to hear.
Just start writing. And then get a technical and a grammar review.
I would recommend trying to keep it simple.
The opposite of progress is congress
In other words, do it in small pieces, and don't try to do everything at once. Once you actually record all the stuff you need to talk about, you can think about structuring it so that people can find the specific facts they're looking for. And of course prettying it up so people won't think you're totally illiterate.
Of course, this is ass-backwards from the way you learned to write in Freshman English, where you start out by outlining your subject, and the actual writing consists of filling in the outline. Some people actually are able to write that way, but I never really cared for it. Sometimes I go through the motions, because the a document plan is something some companies like to see before you start writing. But even when I do write an outline, it's always obsoleted by stuff I learn along the way.
There's a second way to get your CMS documented: hire me.
Analyse your audience. This is probably easy for you - it'll be fellow developers, who probably have a similar level of technical competency and experience to you.
Plan an approach. What type of document will this be? A reference document that is designed to be used when somebody needs to look up a small, highly specific chunk of information? Or a task-based document, that sets out a series of steps to follow in order to achieve an objective? The choice is yours. You may want to do a bit of both, in which case you'll have to decide to what extent you keep the two approaches separate (two different documents, different chapters, different output formats etc.)
Outline, outline, outline. Start writing headings for all the subjects you want to write about. If you use MS Word, the "outline" feature is great for this. At first you might just want to start throwing down these headings without worrying too much about structure. But as they build up you should start to organise them into logical groupings and a hierarchical structure.
It can be helpful to take this to a fairly extreme level where you write a heading for almost every paragraph that you intend writing. You'll probably end up not using all those headings themselves, but the exercise can be a useful form of planning. If you have this level of detail in your outline, when it comes time to actually start writing the text you'll find that the document practically writes itself.
The above advice basically breaks down the documentation task into manageable chunks. I've left out an enormous bunch of stuff, but this should get you started. It also doesn't actually help you make good decisions regarding your audience analysis and document structure. That takes talent, experience, or luck.
Think about this project in terms of the person reading the documentation and using the product. DO NOT THINK LIKE A DEVELOPER. Yes, that's hard. But it is important. Developers are quick to point out little cool things but then fail to explain the bigger picture because it seems "obvious". Nothing about your system is obvious to another person that hasn't been swimming in it for as long as you have.
When thinking like the user, consider the flow of how they will approach it. What are the steps to get started? What are the major features they need to understand? How do the different components interact?
Include lots of examples. Use tools like Photoshop (Essentials is fine) to highlight parts of the screen and bring them out.
Use simple language. If your command of written english isn't the strongest, plan on getting a copy editor to review your work. Also plan on having someone outside of the product read the manual and try everything in it.
DOUBLE CHECK EVERY EXAMPLE, COMMAND, AND REFERENCE. Nothing sucks more than a manual that has incorrect examples.
Look at other documentation that has worked well for you in the past. Also look at popular tools in the same competitive space and see how they do things. Don't neglect another company's manual because the "company and their products suck." If there are a lot of people that use that product, they'll be familiar with that style of documentation. Consistency with things that your users are already familiar with will go a long way.
Be consitent across the entire document. Use the same examples, IP addresses, documents, names, etc. everywhere. Be consistent with your use of italics, bold, and courier print. Keep in mind that arial 10pt is about the same size as Times 12pt which is about the same size as courier 10 pt.
Consider what the final product will look like on screen as a pdf and on paper when printed. If your product does will, manuals will get printed.
Keep chapters in separate files. Makes them easier to edit and protects you from corrupted files. It's always easier to assemble a few files into a bigger file than it is to break apart a huge file.
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
Writing docs isn't that much different from approaching a new software project. rule one for me is to get things structured as fast as possible. people here have already suggested several ways to do this: * TOC / Word Outline view * Mindmaps Those are good when you want a hierarchical structure. Another way to approach the problem are concept maps, which are good to get the basic information in your brain on paper in an ordered way. But you still need to organize it afterwards. Concept maps are also a good way to learn fast how things work together, so they can serve as an outline and guide to the reader. In the end, as soon as you have the structure right, just start writing down whatever comes to your mind. If you feel you have all things down, start going through your document in a linear fashion and see if it follows through and if you missed anything. And lastly, get someone to QA your doc. It is way too easy to write something that makes perfect sense to you while being totally incomprehensible for anybody else. cheers majello
This opinion is mine, you can't have it.