Documentation Strategies? 55
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?"
Start typing (Score:3, Insightful)
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.
Re:Start typing (Score:4, Insightful)
Re:easy (Score:2, Insightful)
If you got to document, do it as you go. You'll never remember all of the critical details.
Re:easy (Score:2)
So you justify crappy documentation and buggy software based on marketing pushing it out the door? Since when does marketing decide that a product is finished or not? If companies would quit throwing buggy unfinished and undocumented software out the door with the assumption that they'll fix the problems in later patches this world would be a better place.
Re:easy (Score:3, Insightful)
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.
Offtopic but (Score:3, Insightful)
Are you sure that it is for fellow developers ?? Sadly, you never know these days...
Not offtopic (Score:3, Interesting)
But it is also possible that this documentation could be used by FAEs who need to have this kind of detailed documentation so that their job becomes easier, more easily repeatable, and faster.
Good documentation is a great thing when it is used for good, it brings customer complaints down and possibly increases revenue. But the double edge also makes it possible to replace the experts with trained monkeys wh
Cards, paper, highlighters, a whiteboard, a floor (Score:4, Informative)
Use color if possible. Get a bunch of highlighters.
A big whiteboard is good as well.
These ideas boil down to using real space to simulate conceptual space. The conceptual space occupied by a manual or any sort of documentation is a lot bigger than a screen or a page. Visualize the whole thing first, including overview, basic concepts, approach, etc., then the sections, then the subsections, finally the details.
--C. Crowley
The big trick.... (Score:5, Insightful)
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 [picknit.com].
How to plan a document (Score:5, Insightful)
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.
Mindmap it first (Score:3, Interesting)
Yellow Post-its (Score:1)
Re:Ask Slashdot (Score:4, Funny)
Because you're not writing documentation correctly.
Basic technical skills (Score:3, Insightful)
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
Re:Basic technical skills (Score:1, Flamebait)
Daniel
Re:Basic technical skills (Score:2)
Incidentally, you're usually best off solving the hardest bit first, since that way if it has any implications on the rest of the problem, you don't paint yourself into a corner (quite so often).
Outline, outline, outline (Score:5, Informative)
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.
Get help. (Score:2, Informative)
Go top down (Score:5, Informative)
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."
Re:Go top down (Score:2)
That alone was worth a (+5, Insightful). Separate documentation should deal with high level design, and rarely if ever the implementation details. That's what comments in code are for.
The other thi
Plan, plan, plan (Score:3, Insightful)
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.
Dude, you're being outsourced!!! (Score:3, Funny)
So you're the CEO or one of the Chief officers? Don't worry. Your job can be outsourced too!
Make an outline and just fill it (Score:3, Interesting)
-make an outline, or TOC for the final docs as I visualize
-make a formatted template for the entire document(s) in the word processor
-do the project, or what ever your work is
Keep a textfile open the whole time with the outline, take notes every day under each outline topic I'm working on.
Final step is just turn the notes into real prose.
Drop it into the templated final docs.
Start writing all that crap down. (Score:3, Insightful)
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.
use a documentation generator (Score:3, Informative)
Think in terms of the user -- not as a developer (Score:5, Insightful)
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.
You need a good book on user documentation. (Score:5, Informative)
If they have an isolated problem to solve they don't want to read the entire thing, or even 1/10th of it to solve the problem - they want a microscope view that includes a very short broad overview then focuses on the salient details so they know enough to complete the task (ie, printing a customer record, or adding a plug-in module) but don't need to know about the intimate details of related modules. This is task oriented documentation.
If they need to understand what the system is trying to accomplish and how individuals in the company use the resource then they need a complete, high-level fly over with examples of why bill in accounting is accessing the same data jerry in manufacturing uses, and how the data gets there, etc. This is process oriented documentation.
If they need to know how the program accomplishes its objectives (laid out in both the task and process docs) then you need a low level, complete program documentation that shows an overview of the data movement and processing through each module/function/database and then a low level view of each module/function/table and how they interact with each other so a future programmer knows that foo won't work properly with a table that has a key length of larger than 128 bit int. This is code oriented documentation, and may include fancy flow charts, uml, etc.
Many self taught (and some traditionally taught) programmers are unaware of the benefits to themselves and their companies of having complete, up to date documentation, nevermind the actual types of documentation and how to go about designing and creating for different uses and audiences. There is a vast library of books on this subject. Two of which come to the top of the google search and appear to be similar to my points above are:
How To Write Usable User Documentation : Second Edition by Edmond H. Weiss (Author)
and
Writing Software Documentation: A Task-Oriented Approach (Part of the Allyn & Bacon Series in Technical Communication) by Thomas T. Barker (Author)
Make sure that you and especially your managers understand that this is not a one time project - if they truly want this done adequately (not even good, but adequate) then it may require as much time to write as the program was to create, if not longer, and that as additions are made to the code the documentation must also be kept in sync, which should double code writing time. Of course, code writing time will similarily be cut in half because you won't have to read the entire commentless program in order to understand how to insert new feature x, so it should be a wash with a much easier maintenance track.
-Adam
documentation? (Score:1)
Simple (Score:1)
I have written the documentation . (Score:5, Insightful)
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
Wiki, if possible (Score:3, Informative)
Basically, a wiki will allow them to easily edit and update the documentation without needing to know HTML code, nor needing to have upload/write access to the documentation directory.
If you're the only one who's allowed to edit or make notes on it, then I'd say the best thing to do is start from the top down, and just keep writing as long as you can. The easiest definition of "the top" is usually the starting pount of the app, essentially doing a depth first search. The problem is, if you go too deep, you'll never get the other areas. So, I'd suggest going no more than 2 screens/areas (or 1, if it's really lengthy) deep before moving back up to the top to go on to the next section.
Once you've gotten all of the major/immediate stuff written, go through again and do the next 2 or 3 deeper pages/areas. Keep repeating this cycle until you have everything written.
Re:Wiki, if possible (Score:3, Informative)
And, as an extra bonus, in case you never finish it, unfinished things look right at home in a wiki!
I wrote a short book on the subject (Score:3, Informative)
just start (Score:3, Insightful)
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
You know where this leads... right? (Score:1)
Audio Commenting (Score:1)
You record yourself talking through a section of code, walking through it's functioning and maybe some history about how you came up with it and why you did it this way versus that way. Then put the filename in your source as an extra comment like "AC 14".
From people I have talked to the major downsides to doing things this way are:
1 A standard file-naming convention needs to be described to store m
Get structured (Score:3, Insightful)
Use CWEB (Score:2)
developer documentation in the same file as your source code. It's a little
strange to get used to at first, but once you give it a try, it makes it
very easy to maintain your software since everything you need to know is
right there in front of you as you develop. The biggest advantage is that
at any time you can generate a beautiful *dvi file that has a table of
contents listing any major sections you've indicated and an index of all
var
Re:Use CWEB (Score:2)
foo.w, and assuming you've got gnu make, simply type 'make foo.dvi'
and it'll make the dvi file for you. Then simply type 'dvips foo' to
print it to your default printer or 'dvips -o foo.ps foo' to generate
a postscript file.
If you happen to know how to use TeX macros, you can, but using CWEB doesn't
require it (I know just enough TeX to created bulleted lists in my
documentation).
Be like e e cummings . . . (Score:2)
The Linux Documentation Project - DocBook XML (Score:3, Informative)
make a list (Score:2, Insightful)
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
Documentation?!? (Score:3, Funny)
Brainstorming tools (Score:2)
I never had to do it but... (Score:1)
I don't even know what CMS is.... (Score:1)
However, I do have extensive experience dealing with writing projects that I can't finish. Based on this experience, I have two pieces of advice:
1. Know the ending before you begin. I realize that, at least at first glance, this makes a lot more sense as advice for fiction writing than for tech writing. But let's stop and think about it. If you could imagine wh
Use a Stranger (Score:2)