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.
On November 9th, 2016, I spent most of the day in anguish. Like many of my friends (and much of the United States), I wasn’t just disappointed. I was devastated. I was afraid for my friends of various backgrounds, afraid for my LGBTQ friends, and afraid for myself. I knew that it was probably that reproductive rights would be rolled back in the new administration. I had been receiving free birth control thanks to the Affordable Care Act and able to make my own choices about what was right for my body.
Unfortunately, that was going to come to an end. I knew I needed to do whatever I could to protect myself before it was too late and birth control became something too expensive to maintain on a monthly basis.
I made an appointment with Planned Parenthood for December of 2016 to get an IUD, without knowing much other than I could be protected for up to twelve years with a one time procedure. For the time being, it was covered, meaning that my IUD would be completely free. It seemed almost stupid not to do it.