Lesson 1: Your first steps to clear writing

Hey software engineers! If the thought of writing technical docs (aka technical writing) makes you want to scream into the void, this series is for you. I break down the writing process into bite-sized articles, so it feels less like a daunting task and more like another interesting challenge to conquer.

Just to remind you, you are not starting from scratch. You've already got many of the skills you need to be a great technical writer. You are masters of logic and crafting elegant solutions in code. You're used to being precise, breaking down complex problems, and explaining intricate systems. That's exactly what good technical writing is all about; just with words instead of semicolons!

Your first mission: Embrace clarity

Clarity is the foundation of good technical writing. Your goal is this: anyone reading your documentation must understand exactly what you're talking about, without any confusion. Whether it's a teammate, a new developer joining the project, or an end-user; focus on making the doc understandable to them!

To make your technical docs more clear, here are 5 simple points you can focus on:

1. Know your audience (Even if it's the future you!): Who are you writing for? What's their level of technical understanding? Keep them in mind as you choose your words and explain concepts. A good trick is, most technical docs for the end user assume the grade level of the user to be between 8-10. This means an average eighth-grader can understand your material! If its highly technical material, the grade level can be higher, around 10-12th grade. Use readability checkers, such as Hemingway, to see the grade level.

2. KISS (Keep it simple and straightforward!): Avoid jargon and overly complex sentences. Imagine you're explaining it to someone who's smart but might not have time to read through the doc multiple times. This is especially true when your audience is an end-user and is not familiar with your industry or technology.

3. One idea per sentence: Short, focused sentences are easier to understand. When you break-down complex information into smaller, more manageable chunks. A rule of thumb is, if a sentence becomes longer than 1.5 lines in your page (in MS Word or Google Docs), rewrite it as two sentences.

4. Structure is your friend: Use headings, subheadings, bullet points, and numbered lists to organize your information logically. This makes it easy for readers to scan and find what they need. Think of it as chunking information into smaller more readable pieces than one big page of text which forces the reader to use more of their cognitive skills to make sense of the text in front of them.

5. Use active voice: Active Voice makes your writing more direct and easier to follow. Instead of saying "The program was implemented," use "We implemented the program."

That's it for our first step! These are simple ideas that anyone could implement. Just start by focusing on making your explanations as clear and straightforward as possible. Try it with your documentation tasks this week.

Stick with this series, and you'll see that documenting your awesome work doesn't have to be intimidating. In fact, it can even be rewarding! In the next installment, we'll dive into another key aspect of technical writing Thinking of documentation as way to communicate.