My love for good, accessible and clean documentation

Published in

Kelly J. Rose was here

7 min readApr 6, 2013

[caption id=”attachment_4759" align=”alignright” width=”300"]

Panda Rose Visual Guidelines (© 2013 Panda Rose, ARR)

When I was in first year at the University of Waterloo, a very large number of friends I had took a course on “technical writing.” It was generally regarded as a smart move with the co-op program since it immediately gave them a benefit they could leverage with early co-op terms before they got more experience under their belt.

I don’t follow the herd well, so I did the thing I usually do. I bought the textbook and decided to teach it to myself. I read it religiously twice through. Once during the school term and once while I was working at the Canadian Space Agency, and used it as a reference many times.

Unfortunately, I don’ t have it anymore because it’s hideously out of date and was in bad shape, but I do have an old copy of the Canadian Press Stylebook on my shelf and Strunk and White kicking around for when I need to verify something.

(I guess it’s important to note though that I don’t follow any of the rules with my blog. This is a free-for-all as far as I am concerned.)

When I wrote up the documentation and procedures for the Payloads team at the CSA, I really enjoyed doing it well. The material was dry most of the time. So, to make it more interesting I spent considerable time laying out the documents so they looked good and matched the CSA’s rigid guidelines. This really energized me, I loved the look of the documents when I printed them out on the high quality printers — They were clean and I could see they followed the rules I had learned from my technical documentation book.

I’ve done a some documentation with wikis, such as Gracefultavi documentation for QA at Net Integration since then. As well, since I program a ton, I’ve documented lots of code code. However, I haven’t really spent the time building up a solid, accessible document template and series of documents until recently. For many years, I thought I’d be able to do it in a wiki, but it has a few properties that make writing clean documentation very difficult.

It’s too easy to clutter a page with nonsense and lack of structure. While the wiki languages generally force a header-level structure. I found that many people ignored these entirely and every page was all over the board, even when you spent the time trying to clean it up. Without a large force of people dedicated to it, like Wikipedia, many pages just got cluttered and useless.
It’s too easy to edit and publish. It is always possible to get the pages to date, since there isn’t a formal publish point. Thus, it is very easy to publish pages that are only half-completed with the intention of completing them later. This generally leads to many pages that are incomplete or wrong making the entire wiki questionable for accuracy and more work than when you started.
It’s too hard to make custom pages for special needs, or it’s too easy to make pages that are an entire mess. You either have a WYSIWYG or HTML editor or you don’t. If you don’t, then good luck making fancy pages without macros. If you do, you can now do whatever you want on every page based on day-to-day whims. Since everything is on it’s own page, one change in look and feel makes all of the content look out of whack with each other.

This all combined to make me not really enjoy building documentation up for many year. I actually found myself thinking it was just a short joy, during a early university period of my life. Similar to how I used to love writing 500 page novels as a teenager, but haven’t been able to get myself to sit and structure out one in a long time.

[caption id=”attachment_4761" align=”alignleft” width=”300"]

Panda Head Guidelines (© 2013 Panda Rose, ARR)

Recently, I was inspired by some work I’ve been doing around ISO27002 and some visual guidelines documents I’ve received.

Since we are going to change the Panda Rose logo entirely soon, I decided to take the new branding and formally write up guidelines around wordmark and logo use both for internal documentation and external uses. With the intention of cleaning up the brand identity and providing answers to all of the questions developers have been asking around how to use elements like the wordmark correctly.

When I started, I didn’t want to end up in wiki-hell where the project would die. So, I decided that I would not only formally define how the stuff was to be used, but also ensure the documents worked within the Word 2010 system for templating and structure. I could learn a new skill and, in theory, create a template that would allow fully accessible PDFs.

As a bonus, the template and style sets could be reused specifically for other documents that are generated for Panda Rose — something to happen very soon with the large amount of immix and standards documentation coming for both internal and external use.

Everything is win-win-win, as long as I enjoyed it enough to follow through.

Luckily, as I proceeded defining the structure and building page after page, I realized how much I loved creating these. I enjoyed spending the time not only getting the typography and the look right, but also making sure it presented the material in as clear of a fashion as possible to ensure that any end user could read it and not miss important details.

I rediscovered that I enjoyed creating clean, and accessible documentation.

[caption id=”attachment_4762" align=”alignright” width=”300"]

Security Guidelines - Remote Access (© 2013 Panda Rose, ARR)

In the last few days, I went even further and started to construct other documents defining our corporate structure. For example, I have been creating a formal security guidelines document for Panda Rose. Inspired by ISO27002 and IBM documentation for the IBMi, I thought I would start with this and work up to a formal security framework.

While we already have clear procedures and structures laid out around this in our internal wiki, I felt that I was enjoying building these documents so much that I would take a swing at that. It was a good check on if I enjoyed building these as it allowed my security geek side to play as well.

Now, I find myself spending more time than I’d like to admit on it. This is beyond spelling out stuff that’s already in our internal wiki. I find myself thoroughly researching the techniques we are using and making sure they are best practices, adding pieces to improve the quality of our servers, and removing security procedures that are useless and irritating to end users.

By forcing myself to write it in a final product fashion, documentation became a fantastic way to force myself to make sure what you are writing is as valid as possible. When what you are writing is not just an editable wiki, but something that is intended to be a final product, at some point, I may hand this to someone and say, “this is the guidelines, please follow them.”

There is no easy opportunity to go back and change them when it’s finalized.

This is it. This had better be good.

And oh man is it fun. I research every word, every detail and I’m learning so much along the way. All this while also ensuring that Panda Rose will improve as a organization with every step. Good documentation and guidelines make for a good organization. Accessible documentation ensure consistency and structure to the organization. Clean documentation ensure that everyone will be able to understand the follow it.

But most of all, writing good, accessible and clean documentation is just plain fun.