An Example of My Process for Technical Documentation
Project
One of my roles at Averetek, Inc. (Now e2Open.com) was to provide internal technical documentation. The development team had been using Microsoft’s Sourcesafe and continued to run into difficulties. The decision was made to move all of our source code to Git and to use Atlassian’s SourceTree as the User Interface. Since this migration required a bit of a learning curve for existing and new developers, some documentation was needed. I was tasked with putting together a guide for using Git with our environment.
The Challenge
Due to the complexities of our development, sandbox, and production environment, combined with maintaining multiple code branches for multiple clients – this was not an easy transition to execute. It required very specific steps. At the time of this assignment, I was providing assistance with DevOps and I had a good grasp of the development systems and the process for pushing our code through the different environments.
My Approach
While outlining and writing this guide, there were some key items I had to keep in mind:
- The target readers are developers. They are smart and they can quickly grasp the technologies being introduced.
- Developers really don’t like to read a lot of documentation. They want to get through it and get on with writing code.
- Pictures and Steps are good. The best approach to showing someone how to do something when you can’t be physically there is to give them a picture (or a brief video) of how to do it and provide specific and individual steps.
- What if considerations. When writing an instruction guide the author needs to think about the “what if” questions that might come up. What if the developer does not have the correct permissions to see the source code? What if the screenshot in the guide does not match what the developer sees?
Test the Writing
One of the things I quickly learned when writing “Adventures in Flight Simulator” is to always, always, always test the steps and instructions after writing. I had a wonderful technical editor assigned to that project and he was great at following my steps and then highlighting something I missed. Not only do I try to test my writing, but I also verbally read it out loud to make sure it sounds correct.
Completion
While I am not able to share the entire document here, I wanted to write a post about it, and to highlight the things that need to be considered when writing technical documentation. It was a fun and geeky project for me. I felt a sense of accomplishment when the developers were using my guide to get them through the migration and back to their assigned tasks.
