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?
There are numerous types of visuals. Here’s a list of options and suggestions of where to use them:
- Still image – this is the perfect medium when trying to visualize a physical product, be it a person or specific object like a type of pan. These can be stock photographs or photos you’ve taken.
- Screenshot – a still image of your screen is great when talking about products that are seen on your computer, such as a website or another piece of software. They’re super easy to take and edit, especially thanks to Snagit.
- GIF – animated images are perfect for explaining short processes (under 8 seconds) which may not be as easily articulated.
- Chart – bar charts, pie charts, line charts, so many types of charts! A chart is the best choice when talking about and comparing a set of numbers.
- Video – the ultimate visual, a video is great for explaining a process. How to make a great technical video is an art form which can certainly be helped by this process but requires much more planning. (Lucky for you, I learned a lot from TechSmith, and they have a lot more to say on the subject).
In this post, I give an example outline to strategically place visuals as well as talk through the importance of testing your instructions. For all of that great information, read the whole post on TechSmith’s blog.
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.
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.
Every two years I redesign my website. It’s an opportunity to be up on modern web design trends, find gaps in content, and re-position the way I think about my skill set. It’s also a way to make sure I still know what my theme looks like inside and out, so that if I do encounter any problems, I know how to fix them.
For this redesign, I decided I wanted to accomplish the following:
- Create a way to sort through projects by skill (web development, writing and strategy, product management, video, etc);
- Create a case study style for projects to better highlight the purposes as well as additional deliverables;
- Remove the resume as featured content, leaving that to LinkedIn;
- Make it easier to contact me;
- Simplify the design.
This site is one of the most important selling points for why you’d want to work with me. I want to make it easy to navigate, while being completely and utterly me.