Crafting Documentation That Actually Helps

10 Insider Tips to Transform Your Writing Process

I know, I know. Writing documentation isn't exactly a favourite pastime for most engineers. It can feel like staring at a blank page, not knowing where to start. We have the knowledge, but explaining it clearly to others? That's a whole different ballgame. It's easy to feel overwhelmed but trust me; it doesn't have to be that way. I've been through the documentation struggle, and I want to share some insights that have helped me turn that intimidating blank page into something precious.

My goal here isn't to give you a template for writing documentation but to equip you with the knowledge to create helpful and informative content.

Let's get started. I'll explain 10 points that you can use to improve your documentation.

1. Objective of the Documentation

   Before elaborating details, define the objective(s) of your documentation. What are you trying to achieve? What problem are you solving for your audience? This clarity will guide your entire writing process and keep your content focused. Additionally, it will help the reader understand whether this document is useful for them.

2. Embrace the TL;DR (Too Long; Didn’t Read)

   

   Only some have the time (or patience) to read every detail. Including a TL;DR section at the beginning of your document highlights the key points and allows readers to grasp the essentials quickly.

   For example, I once wrote a document detailing over ten steps of a process I developed. After sharing it with my team, a few members mentioned that it was challenging to find the exact steps because of the level of detail. Adding a TL;DR section at the beginning solved this issue beautifully. It gave a quick overview, making it easier for those familiar with the document to get a quick refresher without diving into the entire text. At the same time, new readers could still digest the content entirely.

3. Know your audience

   I love this quote from Lilly Walters: The success of your presentation will be judged not by the knowledge you send but by what the listener receives.

   It's all about understanding who your readers are.

   Write in plain English to ensure your documentation is easily understood. For example, simplify your language if you're writing for non-technical stakeholders. Instead of saying "latency," say "response time." If you need to use technical terms, hyperlink them to a clear definition or an external resource for more context.

4. Craft Meaningful Titles and Subtitles

   Think of your titles and subtitles as signposts guiding your readers through your document. Before you start writing, list these titles and subtitles to structure your thoughts. It's like creating YouTube chapters that let viewers skip to specific video parts - your readers will thank you!

5. Ensure Section Independence

   Here's a pro tip: try to make each documentation section self-contained, which means a reader should be able to understand it without having to read the entire document. If there are dependencies between sections, link them for easy reference.

6. Table of Contents

   A table of contents (TOC) is essential for lengthy documentation, providing readers with:

   1. A clear overview of the document structure

   2. Easy navigation between sections

   Many tools offer automatic TOC hyperlinking, which is super handy. Just make sure all links are working properly before you hit publish!

7. Visual Aids make your document interesting

   Remember when you were a kid and preferred books with pictures? Well, much has stayed the same! Diagrams, charts, and infographics can simplify complex ideas better than text alone.

   For instance, I explained how an SSL/TLS handshake can be a real head-scratcher for newbies. I experienced this as a lecturer. I once spent over 30 minutes explaining the SSL handshake process to my students, and only a few grasped it. But then I showed them this diagram.

   The result? More than 90% of the students suddenly understood how it works. It was like a light bulb moment for the whole class. This experience taught me how powerful visual aids can convey complex information.

   

(Source: SSL.com)

8. Keep a Version History

   Have you ever struggled to find who changed a document but couldn't identify the culprit? Yeah, me too. That's where version history becomes your best friend. It's crucial in collaborative environments to let you see what was changed, who made the changes, and when they occurred.

9. Leverage Tools

   So many great tools are out there to help us create top-notch documentation. Personally, I'm a big fan of Notion for organising my docs into easily navigable pages and sections. And Grammarly—oh, it's like having a personal editor catch all those undetected typos and grammar slip-ups before I hit publish.

10. AI Tools aren’t bad

    Some folks fear AI, but tools like ChatGPT or Claude can be beneficial. They're great for proofreading, generating ideas, or even drafting content. Think of them as an extra pair of eyes on your work.

So there you have it - my top 10 tips for turning documentation from a dreaded chore into a powerful tool. Remember, good documentation isn't just about dumping knowledge onto a page. It's about making that knowledge accessible, understandable, and actionable for your audience.

I hope these insights help you as much as they've helped me. Happy documenting, and may your blank pages continually transform into something unique!

If you liked this post, I'd appreciate it if you could share it with other like-minded people.