In October 2017, I decided to apply to Google. It wasn’t the first time I had applied—I applied in 2011 when trying to get a job post-graduation in communications. Back then, I never received a response to my application and expected similar results in 2017.
Although I applied for a product Developer Programs Engineer position in New York, I ended up getting an email from their technical writer recruiter the following week. A year and one day from the day I submitted my application, I signed an offer letter. And 6 weeks after that, I finally went to Noogler (that’s what they call new Googlers) orientation. It was a long road to get here.
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.
Download the full slide deck as either a PDF, Keynote file, or Microsoft PowerPoint, as well as an example proposal.
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.
A few months ago, I wrote a post for five tips to create technical screencasts. Afterwards, I was ask by my former colleague Jessie to write a post for TechSmith about creating visuals for instructions.
Always consider your audience:
- 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.
Five tips for better technical screencasts
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.