Technical Writing: How To Start
Writing is a learned skill. No one person is a good or bad writer. 🙂
When a colleague asked me to mentor them on technical writing, I searched for a single technical writing article, guide, book, or tutorial that addressed three key things:
How people use and read technical documentation
How good headings help readers and writers
How certain tools can help you revise content to be more concise
What I found
Well, my exhaustive searches led me to the depths of the interwebs and back. I found the oldest¹ example of technical documentation in the Western world (it really exists?!) Commiseration about the lack of technical documentation in a field that has nothing to do with software² (it exists?!) And past videos from a technical writing conference³ that I remembered watching and loving, but forgot to save (phew, it does exist).
But–
I still didn’t find what I was looking for. So I was left with two choices:
Provide my colleague with a mix of resources on technical writing: articles, guides, books, and courses.
Create a single tutorial on technical writing with the three things I was looking for.
What I did
I chose the second option. As a reader learning something new, I hate being led to multiple resources – “Just give it to me straight!” I did not want my colleague to have this experience, especially a favorite colleague.
I broke down the tutorial into four parts. By following each part, the reader turns a blank page into a single page of technical documentation. But they also learn so much more; things like:
How to tell the difference between content types, like how-to guides and tutorials
How to structure content so it meets your reader’s goal
How to draft content
How to revise content
How to organize a collection of documents
How to grow the technical writing community by becoming a part of it 💗
How to start
The tutorial will be available through this blog in five parts. Feel free to browse the cheat sheets now, but try not to use them just yet. As you go through each part, you’ll understand why the cheat sheets are the way they are.
Part 1: Learn the different types of technical documentation. There are eight common types of technical documentation, and readers approach each one with a specific goal. This part defines each type and provides real-life examples.
Part 2: Use good headings for structure and scanning. Creating good headings is not easy. The cheat sheets introduced in this part do most of the work for you. ⭐
Part 3: Draft content that’s accurate, consistent, and concise. This part introduces glossaries and how they help you keep your content more consistent. For concise content, guidelines are provided in a cheat sheet for each type of technical documentation.
Part 4: Test, edit, and publish content. The title says it all, but there is so much more to this process. I break things down with a cheeky acronym: A-TEAM: Away, Test, Edit, Approve, Merge.
Outro: What you did and what’s next. The outro recaps what you did – write technical documentation! – and introduces next steps like organizing a collection of documentation, revising existing content, and expanding your technical writing skills by joining the technical writing community.
You may be wondering why you should trust this tutorial over the other resources I found. To be honest, you shouldn't. I don’t say this because we’re in the midst of generative AI, I say this because I want YOU to trust your writing based on the research you’ll do and the content you’ll draft. However, my opinions in the tutorial come from three key experiences, which I’ll get to in a bit.
Right now, I’d like to address the other question you might be thinking: “Why technical writing?”
Why technical writing?
It's because we write more than speak in our day to day work. Slack, emails, code comments, proposals, record of decisions, presentations – the list goes on. So, the need for ideas and concepts to be understood through writing is even greater today.
The goal of technical writing is to explain complex concepts in plain language so they can be better understood by others
On a professional level, many companies include a writing exercise for Staff + engineering positions⁴. And, sharing your idea for a feature, product, or tool in a document that’s easy to understand is more likely to gain the support you need. Your work and thoughts deserve to be heard!
Outside of work, you may have come across technical writing without realizing it. Each one of these guides includes technical writing:
Can you guess what someone might be doing as they read these guides? They’re probably using Roku, Spotify, or Chrome at the same time. In other words:
Readers use the software as they read its technical documentation
Of course, there are exceptions, but the statement is true more often than not. Think of recipes and furniture instructions. Do you cook as you read a recipe? Do you build as you read furniture instructions? Most likely, yes. It’s the same experience a reader has with technical documentation. Even if you don’t use the tutorial, keeping this truth in mind whenever you need to write technical documentation will help you become a better writer right from the start.
So, who am I?
Ahoy! I’m Anila and I like to write for work and play. (No really, I love to write plays.) But this wasn’t always the case. Like most technical writers, my path to technical writing looks like a switchback trail up a steep mountain rather than a straight path across a meadow.
That said, I think every job I’ve had has helped me become a better writer because I’ve used technical documentation at every single job, even when I was a clerk at Dunkin’ Donuts. (Coffee machines are awful to maintain. I recommend a stovetop moka pot.)
The three key experiences that form my opinions on technical writing come from: a former role, being a new technical writer, and my mom. And these are the very reasons why I was looking for something so specific for my colleague.
Sifting through documentation at 2 a.m. or 3 a.m. because I was on-call. I was a systems analyst for an insurance company. The products we supported were written in COBOL, a programming language from the 1960’s. The rest you can guess.
Pining for a guide on content structure. When I started technical writing, I searched and searched for a guide or a tutorial on content structure. Given my experience with documentation at 2 a.m., I knew the importance of structure above all else (save accurate content).
Growing up with a mom who has no patience for jargon, legalese, or doublespeak. My mom taught herself English as an adult and feels that alone is more than enough. I don’t blame her, so I didn’t mind when I had to “translate” English into plain English. This is why I believe you can use simple words to explain complex things. #thanksmom
Up next
Part 1! You’ll learn the different types of technical documentation and become familiar with each type as a reader. Why? Because every writer is a reader first. 📖
¹ See The First Technical Writer in English: Geoffrey Chaucer for details.
³ See videos from the Write the Docs conference.
⁴ Thoughts on the importance of writing from a few engineers: Amy Nguyen, Gergely Orosz , Lorin Hochstein.
