My love for good, accessible and clean documentation

Panda Rose Visual Guidelines (© 2013 Panda Rose, ARR)
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.

  1. 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.
  2. 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.
  3. 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.

Panda Head Guidelines (© 2013 Panda Rose, ARR)
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.

Security Guidelines - Remote Access (© 2013 Panda Rose, ARR)
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.

Enhanced by Zemanta

One day (year) more…

So, 2012 has passed and 2013 is here.

Exciting times to be had by all. Last year much happened in my life, I got married, my wonderful team at Panda Robotics finished the Pandabot Alpha and we incorporated, Panda Rose grew a little (Hello Steve!), and I found out that I will soon be a father. Lots of great fantastic news, and sadly, also it’s share of bad news.

But that’s all passed, and like any stuff that has been used up it’s time to toss it down the chute.

Garbage Chute
Down the chute we go!

2013 will be exciting, not just for Panda Robotics (Beta and release coming!) and Panda Rose (immix on the Raspberry Pi looks like a go and immix api-keys are in place and almost ready for general release), but for my family and life in general.

I know that with God’s guidance and a lot of hard work from my friends, coworkers and family, this will be a great year for everyone, regardless of what happens.

God bless, and good luck!

KJR

Enhanced by Zemanta

Late night ponderings (madness?)

Life is a fascinating thing. It could all very well be stochastic and random, but our minds work so hard to make meaning out of it and to tease out what could only be called a story that there are times when you reflect on the good and the bad and you simply find it impossible to believe there isn’t some purpose or meaning to it.

Some of the best parts and moments of my life happened very shortly after I received deep and painful disappointment at the hands of others, or at my own failure to execute what I believes in. Even now, I regularly am in fear that while I work my best on the projects I truly believe will change the world for the better that I will fail. Sometimes the trolls and the nay-sayers and the pessimists do get the best of me and I worry that the effort is for naught.

However, even if I do fail, or stop, or simply change course, I usually find out that the end product is superior than anything I originally dreamed it would be. Almost as if my dreams aren’t capable enough of putting the pieces together as well as they could eventually turn out. Sure, i’m not a billionaire with my own private plane to Mars like I drew pictures of when I was a child, but I’ve had some adventures I’d never have believed I’d have.

Three things are going on in my life that inspire me everyday and keep me moving.

First and foremost… I’m going to be a daddy… Not much more I can say to how awesome that is. Either  you understand it, and I don’t need to say anything, or you don’t understand it and there’s nothing I could say to explain it to you.

For this, I study my French and German. I’m working on my ability to draw. I’m studying the “art of manliness” and practising my ability to read bedtime stories. I can’t even wait to get her out to the baseball field and play a game of catch (or him… we really don’t know yet.) I don’t know if I’ll be a good father, but I know that the idea of it inspires me to work even harder every day.

I am a co-founder of an amazing company (Panda Robotics) with an amazing product that impresses me every day as we improve it and add more and more capacity with the capital we do have. Liav, Felix, and everyone else always amazes me at how they can work with me to squeeze out of every moment, every dime, every item that little bit more to create a product that just… Well, you have to talk to people who’ve seen it in person. It’s just that impressive.

Yes, I dream bigger, and I pray at times that God (or the Universe, or *insert your diety here*) will come through and let Felix, Liav and I take this to the level it really could be brought to, and from that dream and wish I work hard every day to try and make it come true. You see, I really believe that 3d printing is going to change everything, it’s only a matter of building it and getting the next generation learning it young. Just like all of us grew up with Apple IIs and created this revolution. The moment Pandabots (or something similar) are in schools and homes with children learning how to create 3d objects young, that will be the moment that the 15 year clock to the real next industrial revolution will start.

However, I must say that seeing Liav come up with innovative ways to make 3d printing accessible, or seeing Felix’s enthusiasm shine through when he’s working on the business with me. There’s not much more you can ask as a co-founder.

Finally, there’s Panda Rose, my company I started a few years back with some of the most creative programmers I know, and our software immix. Every day I learn about new features that Stefen has implemented, or adjustments to the basic framework that make it so much easier to wire everything together in this beautiful holistic framework. Some of the new stuff coming down the pipeline changes everything. It truly turns immix into a framework for the internet of things.

I’m always proud to see the work that JF does for our clients ensuring that their every need is met, even if they aren’t 100% sure of their needs in the first place. It excites me to know that Steve is making sure that the product won’t just be accessible, but will be fully internationalized so people of every language will be able to use it effectively.

There’s also Becky, who keeps me sane and happy at the office, even while she reminds me that I need to put more pressure on my clients to ensure the A/R doesn’t keep on growing without converting into CoH. She’s the reason I’ve been able to concentrate on what I do best, and hopefully building a few of these dreams into reality.

Yes, it’s stressful, and yes, there are days that I just don’t know what to do, and yes, even sometimes I wish some of my clients understood how much I really do care about what I do for them. Yet, I know that I do my utmost best, my team is amazing, and that Panda Rose is the epitome of the phrase, “We don’t know what impossible even means.” We all dream big, so our clients can dream even bigger. It’s wildly fun.

In the end though, it all seems to be building to something, and this is going to be an exciting ride.

Have a great night everyone, and I hope this week will be the start of something even more amazing.

KJR

Enhanced by Zemanta