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
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.
Are you sure that it is for fellow developers ?? Sadly, you never know these days...
If you got to document, do it as you go. You'll never remember all of the critical details.
You are being MICROattacked, from various angles, in a SOFT manner.
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.
This is the question that almost everyone, everywhere, that deals with a complex system has to deal with. Whether you're programming a kernel or writing documentation, you cannot understand everything at once. You need to start at a small section of it, and simply thread your way through the task until it all begins to form as a whole.
--Stephen
Did you ever notice that *nix doesn't even cover Linux?
If you'll want it to be usable by anyone, resist the temptation to "just start writing" and plan it extensively. Write down what the main categories should be - what are the main components of the system, and more importantly, what are the main categories of people who will be reading the documentation? What are they looking for?
Expand each main category into subcategories. Keep going until you have a detailed outline. By the time you have a good outline, you probably will have reorganized/reconsidered everything several times... but if you have a good outline, the only thing left is to fill in the gaps, which will be tedious but straightforward.
ClutterMe.com - easiest site creation on the Net. Just click and type.
Use a combination of index cards and an outline. Every little idea or concept - jot it down on an index card. Use the outline to start bringing all those pieces together. It'll be chaotic at first, but as you think of something that needs to be documented, add a note somewhere in the outline and bung the rest on a card.
Be prepared to shuffle the cards around quite a bit until the structure seems right, but that's the advantage of index cards. But the real important thing is to make sure that you write things down as they come to you, rather than trying to remember to write about it later - you'll forget.
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
Just start writing.
It's the same principle with beginning writers. It doesn't matter if you throw away what you write the first hour or two - it will get you working. Just start pouring stuff out. Write a paragraph describing something. Now detail the systems that relies on. Now describe those systems.
Now start again because you're jumping around uselessly - there are some core (or nearly core) systems listed there. What other systems are there like that - start documenting those in a uniform manner. Reuse anything you wrote that described things well - ignore anything that didn't.
Try not to think too linearly - if you need to get something out, just get it out - you can move bits and pieces around very easily later.
as far as organization....
Personally I like to do this but with a hierarchical editor. Unfortunately, there's not a decent one (IMO) available for linux. I used to use Progect for Palm - they have a desktop companion for Windows you could try - though it didn't install under Wine (for me). ymmv
cyn, free software and *nix operating systems enthusiast.
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.
Since when does marketing decide that a product is finished or not?
All the flipping time.
And if you're really lucky, they'll tell you.
Take this from someone who found release candidate n had been approved, duplicated and shipped to retailers, while he was still up all hours submitting candidate n+2 for testing.
I find that when I need to write some documentation or write a policy, etc.., it's best to begin making a list of everything you want to say. Do not worry about order or organization at this point. You just want to make sure that everything you want to say gets on that list so that you don't leave anything important out. It is preferred if you can spread this process out a little bit, as you may not remember everything you want to put in the list during the first go. Also, you might come back later and start adding subtopics to any of the items in the list.
Once you feel your list is complete enough, go ahead and try to organize it logically, probably outline it out by topic as previous people have suggested.
When you think you are done, always have someone else read it. You will want someone out of your target audience to read/proofread as well as someone very close to the project, perhaps one of the other developers. They might be able to add some insight or think of something you didn't.
As an aside, it is good to google this sort of thing, as others before you have been through the same process. Obviously slashdot is a great place to get input as well.
Good luck!