I’m back with part 2 of my thoughts and experiences on technical Documentation. This time, I’ll be looking the types of documentation, and a few tips I’ve picked up.
Types
The first point you will likely find is that there are many types of documentation.
Procedural
Procedural is probably the first method of documentation most people create and is always the easiest. It can form the basis of more detailed documentation or the first step on automating / scripting a solution.
It’s typically formed of pure and simple step by step of tasks done, and commands run, for example:
- Install Server.app from the MAS.
- Configure user accounts.
- Configure file shares.
- Configure access groups.
This is how I wrote my first internal Munki documentation.
Note: This is not fully detailed and possibly not suitable for handing over to a less experienced engineer or to provide handover training. This would, however, possibly be suitable for engineers at your level or higher.
Verbose
Verbose documentation is probably the second type of documentation you’ll progress to. It typically comes from the procedural documentation and, as you can imagine, will detail the exact buttons clicked, and commands run. For example:
- Login into the local administrator account (“username” and “password”).
- Click the Apple logo in the top left corner, then “App Store…”
- Click in the search box (top right) and search for “OS X Server”.
Etc.
This was what I converted my Munki documentation to for our internal usage and formed the basis of the blogs I’ve posted.
Note: This is now fully featured and suitable to be given to a junior staff member in very specific scenarios. However, as it does not explain in detail why each task is performed, it isn’t great for knowledge transfer or to help the engineer to adapt should the scenario not fit the documentation.
Descriptive
Descriptive documentation typically forgoes the use of fully detailed instructions, to instead concentrate on detailing the reasoning behind the tasks. It typically assumes either:
- The reader has some knowledge of the tasks.
- The reader has no interest on how to complete the tasks but more the reasoning.
Note: This type of documentation typically isn’t suitable for junior staff members as they may not have the necessary knowledge to fill in the blanks. However, this will typically be fine for Managers and Supervisors (tweaked to the appropriate audience).
Mixed
This type of documentation is a mix of options, typically Verbose and Descriptive. This will likely explain the reasons behind a certain group of actions, or in some cases explain the reasons behind every action (although this is possibly overloading the reader).
A great example of this kind of documentation can be found on Rich Trouton’s blog, for example this article here.
Note: This documentation would typically provide good documentation to hand over to multiple members of your team, including juniors and to assist with knowledge transfer.
General Tips
Speaking of knowledge sharing, here’s the tips I’ve come across whilst having to write documentation. Some are from experience, and some I’ve been taught from others.
Don’t be afraid to use Graphics!
Just because your document is desired for other engineers doesn’t mean it needs to be pure text. Some people are more visual learners and can understand a diagram better / quicker than a block of text. Other items might take pages to explain in text, or one page of a nice diagram.
For diagrams I typically use OmniGraffle, although one of my colleagues has created some great ones with Keynote.
If your documentation is a guide to doing a task, chuck in some screenshots and images. Preview on OS X Yosemite includes ‘Markup’ so annotating these screenshots can be quick and simple. This also allows the reader to spot any changes from the documentation and what’s in front of them easier and quicker and alert you to any potential changes (maybe an OS X update changes the options on a dialog box, for example).
Don’t forget tables! If you’re writing lots of related information (such as an application list with version numbers), you are often better including it in a table rather than a list of bullet points and tabs.
If in doubt, include it.
Although typically this will cause you to write longer documentation, it’s a good mantra to use. If you are unsure if you should include a piece of information, then you need to include it! Worst case, it’ll ensure your documentation is thorough. Best case, it’ll contain the vital piece of information required for a rebuild.
If it’s confusing, spend more time explaining it.
Pretty self explanatory and also links back into using graphics. If it’s complex or confusing, dedicate more time to it. Use graphics and diagrams. Possibly even go so far as to split the information off into it’s own section or even it’s own documentation!
Layouts / flow.
Ensure the document is clean and reads well (and makes sense!). Try to keep related items together and not spread throughout the document. When documenting a full solution for a client, I will tend to use the following template document sections:
- Introduction
- Brief summary of the project (1 paragraph)
- Overview of the entire solution (1-2 pages)
- Server Configuration (typically subdivided between areas, e.g. “Mac Server Configuration”, “Casper Server Configuration”)
- Installed Hardware (Serial number, specs, warranty)
- Storage configuration (the arrangement of any storage, RAID, partitions, names, what each is used to store).
- Backup Configuration
- Services Configuration (arrange by Apple and non-Apple first, then alphabetically, each service in it’s own sub-section)
- Client Configuration
- Installed Hardware (Serial numbers, specs, warranty)
- Groupings (such as per room and / or department)
- Management settings
- Printing configuration
- User experience (at login, use and logout)
- Appendices
- Full password list
- License codes
- Online accounts (such as Apple IDs)
- Deployment crib sheet (verbose still documentation to assist with redeploying client devices)
Reviewing
This is an important one. Have someone else review your documentation. If it’s instructions (such as a deployment crib sheet) have them run through the steps. This will test that the documentation makes sense and is actually correct. I’ve often found that I’ve skipped over a mistake I’ve made as I’ve unconsciously knew what I meant but it wasn’t what I typed. Often, the reviewer can also have better ways to explain an item that you hadn’t thought of.
Archive
This one can be done with a Wiki or manually using version numbers, but I’d always recommend keeping archives of older versions of documentation, as well as the current ones. This allows you to ‘roll back’ any areas that you’ve changed your mind on, as well as refer back to them to confirm the dates a change was made.
Summary
That’s it (for now at least)! We will now return to your regular scheduled technical blogs : )
As always, if you have any questions, queries or comments, let us know below and I’ll try to respond to and delve into as many as I can.
Further Reading
Most of this blog is from my own experiences but I can’t lay claim to it all. If you’re looking for further advice or reading around the subject of documentation and time management in general, I’d highly recommend reading:
“Time Management for System Administrators” by Thomas A. Limoncelli