Aug 26, 2016
Five tips for improving your technical writing and documentation.
Get more users and fewer support requests by leveling up your writing and technical documentation.
If you’re working on the web, at some point you’re going to need to write — even if you’re a designer, a developer, a programmer, a not-writer.
For example, almost everyone needs to write technical documentation (such as your README, your internal docs, your external docs and help manuals) but you might also need to write the introductory copy on your app’s homepage, your “about” page content, or a blog post. We can’t escape the act of writing.
In university, I nearly flunked my introductory grammar class, and I still struggle with writing to this day. However, nearly ten years later, I’ve authored two books, launched a startup, and have written countless blog posts for three different blogs. Writing has taken my career to new heights and there is a lot I’ve learned over the years.
There are quite a few small, easy things I see missing from a lot of folks’ work that would immediately improve how well their technical writing and documentation is experienced, understood, and enjoyed. You don’t need to be an expert to write on the web — you just need to be able to write well enough.
My top tips for writing technical content:
Write like a human, not a machine.
Don’t be afraid to be funny, creative, and a bit silly. I love and encourage personality to shine through your writing. Reading is so much more enjoyable when you sound like a human having a conversation with your reader, rather than dictating instructions.
I took this to a bit of an extreme with the introduction to my first book, Hello Web App:
I wanted folks picking up the book for the first time to have an immediate indication that this book isn’t something that takes itself seriously—that the book is going to be fun and down-to-earth. As Hello Web App is geared towards getting people into programming (which can be intimidating and terrifying), being goofy at the start reassures my readers that programming might actually be fun.
The content of Hello Web App is a bit more professional, but still has some “Woohoo!”s and other silly, down-to-earth sentences throughout the book:
I’ve had so many readers tell me that they’ve enjoyed the fact that the book feels informal and conversational, and that helped them feel more confident in finishing the book and jumping into programming.
Remember that your readers aren’t exactly like you.
This happens in a lot of “advanced” level writing. The writer feels like there should be a certain level of knowledge needed before using their project, so they skip over explanations and instructions. After all, advanced-level readers should know all that, right?
However, a lot of people get to “expert” level in a lot of different ways and paths and assuming previous knowledge is dangerous. You can exclude a lot of potential readers by glossing over instructions. Just because your project is most useful to Python developers with multiple years of experience doesn’t mean that your readers have all the exact same level of knowledge.
Plus, sometimes it’s nice to get a reminder of how to install something again.
I’ve been coding for many years and have written a couple of books on introductory Python development, and I still feel like a complete dolt when it comes to a lot of project’s installation instructions.
A few helpers:
Helper #1: Create a persona and write for them.
Try to think of ways your readers could come to your project without having your exact skillset, and give those ideas (personas) a name. You could think of, “Dave, a sysops with experience in C but not in Node,” and review your text, then switch over to “Carol, a developer lead,” and try reading what you wrote from that different perspective.
Helper #2: Take a break from your writing and come back to it later.
Sometimes you just need to step away for a bit (a couple hours or even overnight) to see your writing from a different perspective. Try changing locations, or changing projects for a bit. Going back and forth between contexts can sometimes shake some new ideas loose.
Helper #3: Run your writing by a friend, colleague, or helpful stranger.
Getting a second pair of eyes on your writing, even just a review, can help you find issues. Friends can especially help find places where you’re skipping instructions or where your writing feels robotic.
This can backfire a bit if your friend just wants to be helpful (“Everything looks great!”), or, if your friend struggles to find something to critique and feels compelled to mention something that actually isn’t an issue.
In general though, getting a review from an outside perspective will almost always help rather than hurt.
Helper #4: Use gender-neutral terms.
I see this so often in writing about startups and entrepreneurship:
“The founder should do this, and then he should do this.”
As I’m struggling to be validated as a female entrepreneur, those references are immediate reminders that I am usually assumed not to be a founder. That’s the kind of feeling women in the tech industry gets when your writing includes only male pronouns.
It isn’t hard to remove gendered terms from your writing, it just might take a bit of practice to remove the habit.
This article (Gender-neutral Technical Writing on TechWhirl) is my favorite resource regarding removing gendered terms from writing, with clear examples of problematic sentences and how to make them more inclusive. Not hard at all.
Helper #5: Remember that terms are obvious to you might not be obvious to others.
To illustrate this, let’s take a look at the world of cooking. If you’re new to cooking and open a random recipe, you’ll likely encounter terms you haven’t seen before:
“Truss the bird.” (What the heck does truss mean?)
“Cream the butter.” (Isn’t butter already cream?)
“Shock the vegetables.” (How does one frighten vegetables?)
Recipes are particularly bad about adding additional instruction, relying on the reader to simply Google the terms mentioned. But we don’t and shouldn’t do that for technical writing — adding helpful, short, additional instructions isn’t hard and doesn’t distract.
If you don’t want or feel it’s appropriate to add additional instruction on what something means, you can simply add a link to a helpful resource:
The Laravel documentation above references Composer. If no link was added, the reader would assume that the writer assumes knowledge of Composer — so if you’re unfamiliar with Composer, this project is not for you. That would be exclusionary.
However, simply by adding a link, the Laravel documentation is saying, “It’s okay not to know what this is — go here to learn more,” making their documentation more inclusive and welcoming.
Cut down the amount of content you have and use appropriate formatting.
Huge paragraphs and essay-like blocks of text are intimidating. People don’t read on the web — they skim — and a huge block of text won’t be read.
Reduce and simplify your content using these tactics:
- Cut down your content to two to three sentences per paragraph. No use blocks of text.
- If you can’t shorten a paragraph, try breaking it up into bullets to make it easier to skim.
- Use italics and bolding to highlight the relevant parts of your sentences. These bits will catch the eye and will invite the skimmer to read the entire block of content.
For example:
The block of text on the left is hard to read. Sure, you can read it, but it’s certainly more difficult than the right.
By splitting it up into bullets, adding strategic bolding, and breaking out the headline, we’re making it easier to skim and easier to see the important bits of the paragraph at a glance.
Simplify your language
Don’t be fancy and break out the thesaurus when you’re writing. Simple, clear writing not only is easier to read for English-fluent folks, but it’s also easier to translate into other languages. Don’t forget someone could be reading your documentation and writing using Google Chrome’s translate feature. Simpler language will be easier to translate.
Add multimedia like screenshots, videos, and gifs to illustrate your writing.
Add helpful screenshots and multimedia when you’re writing instructions and guides.
Shopify does a great job of this in their documentation. Not only do they include helpful screenshots along with their instructions:
They also use animated gifs to illustrate a described process:
When you add visuals to your writing, folks following your guide will be able to visually match what you’re describing, making your instructions easier to understand and implement.
Last but not least, if you’re worried about the act of writing: practice, practice, practice.
Write as much as possible, and slowly but surely it’ll get easier.
Remember to try to simplify your writing (both in length as well as complexity), and remember that your readers will have different backgrounds and experiences than you.
Write as much as possible. Write like a person, not a robot.
