There is something special about Write The Docs. I’ve been to a number of conferences in the last few years, many of which were tech-specific, and this is the only one where I feel confident that I could have walked away friends with everyone. People who attend this conference are kind, smart, thoughtful, and every other adjective you’d hope for your communicators.
I was honored to be among the 15 speakers chosen to speak. On Monday, September 10, I presented, “How to tear down your existing documentation,” focusing on the ways writers could write a proposal to convince their managers that the documentation needs to be blown up.
In a few months, I’ll be joining the technical writers community at Write The Docs Prague. I’m thrilled to have been chosen and I look forward to meeting my fellow writers. Check out my intended abstract:
How to tear down existing documentation and rewrite docs that actually work
We all know what it’s like to look at a series of existing documentation and think, “how did this happen?” Be it a large swath of unorganized content or a lack of a clear strategy, the complications of bad docs aren’t just a curse for documentation editors. Our readers see it, too. It leads to confused support requests and possibly a loss of customers.
Over the last three months, I’ve written a series of four blog posts about creating and managing instances with Packer and Terraform. It’s been a tremendous learning experience, and I couldn’t have done it without the help of some HashiCorp experts (and ex-pats). Thanks to Sean Chittenden, Paul Stack, and Justin Reagor for your advice, critique, and editing.
Below I’ve included excerpts from all of the posts. The source code for all of the exercises is available on GitHub.
Are my readers already experts? Have they done this process before, if not exactly then in similar circumstances?
Are my readers internal or external? If my readers are within the same company, what language do we share that will help better explain the process?
What mood will they be coming to my content with? Am I creating this content for someone who is in a rush to get something done, or is this for a more casual learner who is just hoping to further their education on a topic?
What is most important to my readers? What is least important?
How do my readers prefer to learn? Do I know if a blog post is more successful than a video? Is there any analytical data to support these claims?
Are my readers native English speakers? If I use an idiom, will it hinder their ability to learn how to complete the process?
As the documentation editor for Joyent, my work has been split in three ways: technical blog posts, screencasts, and actual documentation. I find the most fun with the first two—as important as actual documentation is (and it may be the most important), there’s little room for creativity and an editorial voice. Technical screencasts can have a bit of fun flair, but still must be accurate and (most importantly) instructive.
The more videos I’ve created, the more I’ve learned about how to craft watchable content.
1. Be as brief as possible.
Although there are instances where longer videos come in handy, such as in-depth step-by-step tutorials or publishing webinars, many users don’t have the patience to sit through long pauses or over-explanation of a topic.
A few weeks ago, I was presented an opportunity to work with kids age 9-16 and teach them “how to build a website,” via Opportunity Music Project. I was told there would be internet access, about five hours of teaching time, and thirty kids in the class. While I always knew that teaching was hard, there’s nothing quite like hands-on experience to prove a thesis.
All in all, it was one of the most challenging and rewarding five hours of my professional career.
There were a number of great moments and missteps along the way. I hope to take these as lessons for future opportunities.
Lesson 1: Set realistic goals
Before class started, I had been asked to help all of the kids leave knowing how to build a website, plus talk about internet safety. Going in, I knew there was no way I could ensure that every kid had the skills to build something right away. But, I knew I could give them a basic understanding of what HTML looked like and the tools to continue to learn when class was over.