Good documentation

• Avoid duplicates early and try to get individual’s documentation to start being a departmental value. Centrally locate documentation, encourage users saving in a similar method and not copying to their own storage to edit or save.
• Always discuss documentation when performing a post mortem meeting after issues
• New systems and employees are the perfect oppurtunity to create documentation on, especially since there will be questions that have to be answered several times due to inexperience
• include the purpose of the document, documentation storage location, or documentation project in a highly visible area so there is no question about what they should accomplish. Then review whether this purpose is met when the documentation is utilized
• Include the why when documenting installs and troubleshooting. You’ll teach other staff more about the purpose of each step and provide an explanation in the event things go wrong or the steps are used for a similar but not exact situation

I’ll add more as it comes to me

That brings an interesting (to me) point. What good does knowing the audience do for a writer?

Say that one document will be for “Non-technical users” and another document will be for “System administrators”. A writer is tasked with both documents. Should the same writer be expected to create the same quality of document for two different audiences?

I assume that most of my product documentation will be used by someone close to the “System administrators” group. The purposes of the products tend to be aligned with those job functions.

After almost 40 years in programming, it’s difficult for me to get into a “Non-technical users” mindset. Many words are so familiar to me that they don’t ring alarms to me when I use them. I simply don’t ‘know’ that “Non-technical users” won’t know what the words mean. The words are common knowledge… right?

Well, of course they aren’t. But it can be tricky finding a balance, especially when “Writer” isn’t your occupation in the first place.

So, what good does it do to know the target audience when you are certain to have a different “language set” from anyone who isn’t in your particular group?

Maybe the good that it ought to do is that writing tasks should not be assigned in the first place to someone not in the target audience group. (Apologies for the two “nots”.) If you aren’t comfortable with the language of the target audience, maybe you shouldn’t be writing for that audience.

Tom

Often documentation is poor because there really is no standard that we train technical people to follow. Unless you’ve worked with or as a technical writer there’s no consideration for writing formats, conventions, etc.

I’ve made a lot of money cleaning up databases where nobody defined how to write Suite… or is it ST … or STE… or # or… well it goes on and on. I’ve seen where addresses put in first name fields and many, many other data entry problems.

So it’s not surprising that a technician isn’t able to document their own stuff.

When writing documentation I think the first and most important thing to understand is who the audience will be who is reading the documentation. Non-technical users… System administrators… or someone in between.

I’ll document the audience in most documents I create.

Next I’ll create the Purpose of the document. Is this a step by step process document, or just a high level briefing on a problem? Perhaps this is a change control log or a troubleshooting ticket that will need to be read by the next support tier above me?

When I am studying documentation I’ll actually take notes for myself. I’ll highlight commands that worked as I’m working through the process… I’ll read back a few steps when I’m on a goose chase… then when I have the process down, I’ll erase erroneous pieces and test my documentation again.

Project proposals are the most interesting documentation to create. Here the technology needs to be accurate, but the conclusion will need to be presented to a manager whose concentration level is about 30 seconds. Converting the reporting from technical into business language and using keywords he understands can make or break a new project proposal.

I think the rules should be

A) This is boring technical writing not creative writing
B) Always document the same way over and over again
C) Imagine what your audience is looking for and only share what they need
D) Quality control – Have someone check and edit documents for content, grammar and continuity.
E) Create a style sheet and forms that reduce the need to write anything. Check boxes, radial buttons and drop down boxes for the most common situations. Avoid text boxes…
F) Always document digitally, into a database whenever possible in order to take advantage of search options.
G) Oh… Have I mentioned consistency yet?

I’d also like to put in my 2 cents in for internal Wicki’s that allow documentation by amateurs that can be quickly edited by experts.

Echo Connie14K’s point of make it accessible – you cannot always predict who needs the information or who might leverage that information for an improvement.

I will try to remember this discussion next time I need to add to some doc.

I have always written documentation (Programmer Annotations. Technical Guidance, or Instructions) as I am working through each application/program install or upgrade. I actually did this to help me understand the concepts and get through a difficult procedure… just in case I needed to do it again. I found that ultimately, my documentation was passed onto the next programmer or admin to help them understand.

Documentation should NOT be hidden – it should be made available to all who support or use an application or program or Operating System regardless of the fact that it may be too complex/confusing… let the person who reads it determine that.

I have tried to write documentation for the user or a newbie. I have heard some say that it’s too simplistic for admins, but I don’t tend to care. There is no room in my life for elitism or smugness. Besides, it gives the next admin a good foundation for understanding. From that, they can add to the documentation and maintain it as a “living” document.