How to Write a Better System Administration Guide

What do System Administration Guides and Mozart have in common? There’s a scene in the movie Amadeus where the Emperor asks Mozart to take out the boring notes. He found it too long.

“Cut out some parts here and there.”

“Which notes, your Emperor?” said Mozart.

The Emperor tried, got into a tangle and then left in a huff.

If you work as a Technical Writer, every now and then you’ll be asked to reduce the word count.

How to Write System Administration Guide

For example, on a recent project, the CEO said, “Make the System Administration Guide shorter.”

As a freelance Technical Writer I didn’t how ‘short’ was short. Or which chapters to remove? Or which parts of the System Admin Guide were too long?

But you have to try to make the documents more useful. That’s what you hire a tech writer to do, right?

However, the problem when writing System Administration Guides (aka System Admin Manuals) is that they’re often written by someone else. Your job as a tech writer is to improve the current text.

Or, if you’re starting from scratch, you may not get clear direction on what should go into the document.

• Do you have a System Administration Guide template?
• If not, do you have guidelines on style and formatting?
• What do you want in the table of contents?
• Is this enough information?
• Do you need graphics?

And so on…

The temptation is to continue adding to the sys admin guide until you’ve covered ‘your’ bases, which of course may be overkill.

But, if you’re not getting direction, then it’s hard to know where to draw the line. How much documentation is enough?

System Administration Guide: Reduce the Word Count

What the CEO meant – as I later found out – was that the process of writing technical documents seemed to take forever. He needed to control costs. Writing these documents was getting expensive.

Instead, he wanted a ‘minimal usable document’ for sys admins.

In other words, develop a sys admin template and use this to capture critical tasks. And remove the waffle.

Our aim was to reduce the word count without undermining the accuracy of the document.

Here’s what we did.

1. Plain English – Used Plain English writing techniques to write the sys admin guides. This one change had a domino effect on the rest of the text.
2. Better Summary – Long, rambling introductions were reduced to one or two liners. Suddenly, the document had more impact. You, the Sys Admin, could get the answers you needed faster.
3. Task Based – We changed the table of contents so that each topic was a task, e.g. How do I install the server? This Question and Answer format simplified the text and reduced the word count. We deleted topics that didn’t fit these criteria or moved them to the appendix.
4. Emperor – We purged the document of all jargon and TLAs (three letter acronyms). This made the document easier to read.

System Administration Guide: Format, Edit, Delete

Next step? Look at the System Administration Guide template and see how we could improve the format.

1. Tables & Matrices – Presentation and usability was further improved by displaying information in tables and role-based matrices. This content hierarchy helped Sys Admins find information faster, making the documents more useful, and reduced calls to other support channels.
2. White Space – By making better use of white space, the sys admin manuals become easier to read; this meant we didn’t need to write as much supporting or explanatory text. It seems the older System Administration Guides were very difficult to read, resulting in disuse and an unwillingness to consult the guides for information.
3. Font – The previous Technical Writer had used a ‘trendy’ font for the documentation suite. While he may have meant well, it made the documents difficult to read, especially when printed out and read in poor lighting conditions. The revised documents used an easy to read combination of Arial for Headers and Times Roman for the body text. What it lost in glamour, it gained in usefulness.
4. Remove Filler – We looked for ways to remove articles, adjectives, adverbs, prepositions, pronouns, and other descriptors when possible. Your sys admin guide is not a novel. The reader wants to find the exact piece of information now. Don’t clutter the page.
5. Eliminate Redundant Words – Instead of saying, “in the event of”, write “if” instead. Remove the fat. Look for phrases (often found in Introductions) that add little value and clog up the page. Keep introductions brief. Then bridge to the main content.
6. Eliminate Redundant Phrases – If you find a phrase like, “The color blue,” remove color. Or, “Past history shows…,” remove past, i.e. anything that is history is in the past.
7. Long v Short Words – Do you ‘procure’ or ‘get’ something? It means the same thing to most people. However, if you habitually use longer, more complex words throughout a document, the word count increases, while the quality often suffers.

Conclusion

You can reduce the word count in System Administration Guides by using shorter words, avoiding jargon, and striving for simplicity.

Ask yourself: What’s the fastest way to explain this? Then write it. What else would you add?