Notes on Technical Writer

Since the very start of my career, I have viewed technical writing as more than just a means of communication—it’s a powerful tool for both teaching and learning.

The process of organizing thoughts, and presenting them clearly often benefits the writer as much, if not more, than the reader.

In this post, I aim to capture some of the lessons I’ve learned, the tools I rely on, and the principles I follow to make technical writing a meaningful and impactful craft.

General Rules of the Trade

1. Clarity Is Key

Technical writing should simplify, not complicate. Follow these golden rules:

  • Break down instructions into small, digestible steps.
  • Use links, screenshots, and examples to guide the reader.
  • Include the expected outcomes for every process.
2. T-Shaped Approach for Deep Dives

When explaining a topic:

  • First, provide an overview to cover the breadth of the subject.
  • Then, choose an aspect to dive into, offering depth and detail.
  • Use Google’s Style Guide for consistency.

Core Techniques from Google’s Style Guide:

  • Write in the active voice to clarify actions and actors.
  • Use numbered lists for sequential steps and bulleted lists for non-sequential points.
  • Write in the second person, addressing the reader as “you.”
  • Place conditions before instructions, not after (e.g., If the file exists, then delete it).
  • Format code or technical terms using code font.
3. Understand and Think Like Your Audience
  • Who is your audience? Create personas with attributes such as:
    • Role: QA Tester, Developer, or System Administrator.
    • Goal: Restore a database, deploy an application.
    • Knowledge Base: Familiarity with Python, command-line tools, or Linux.
  • Adjust for inclusivity: Avoid jargon unless your audience is well-versed in it. Provide definitions for unfamiliar terms and include links to additional resources.
  • Strike a balance: Avoid over-narrowing your focus to one persona. Broaden where possible to be inclusive of diverse readers.
4. Write, Review, Improve
  • Read it aloud: This ensures conversational and engaging writing. If sentences feel awkward, rephrase them.
  • Take breaks: Step away from your draft to gain fresh perspectives.
  • Change context: Print your draft or change fonts for a new perspective.
  • Seek peer feedback: Like code, writing benefits from constructive reviews. Ensure your reviewers understand your style guide.
5. Code Integration Best Practices
  • Always include line numbers when providing code examples and refer to them in your explanations.
  • Offer a link to the full code (e.g., GitHub or Gist) at the beginning of the document.
  • Use visual tools like Slides Code Highlighter to make code stand out in presentations.
6. Use LLMs as a Tool (only a tool)

Leverage Large Language Models (LLMs) such as ChatGPT, Claude and others to:

  • Edit and refine your drafts.
  • Refactor sections for clarity.
  • Never use it to think for you!

Tools to Elevate Your Writing

Here’s a curated list of tools (that I personally use) to boost your technical writing:

  1. Slides Code Highlighter
    Highlight code elegantly in Google Slides.

  2. Manim
    Create high-quality technical videos and animations.

  3. Draw.io
    Craft polished technical diagrams.

  4. Grammarly
    Refine grammar, spelling, and readability.

  5. Hemingway App
    Assess readability and improve sentence structure.

  6. Write the Docs
    Join a global community for resources, workshops, and support.

Parting Thoughts

1. Prioritize the Reader

Your audience is the heart of your writing. Focus on their needs rather than how much information you can cram in.

2. Simplicity Is Hard
  • Know your audience’s knowledge level.
  • Use clear, concise language.
  • Structure content logically, with easy-to-follow steps.
3. Community helps, a lot

Technical writing is not a solitary journey. Engage with communities like Write the Docs to grow, learn, and refine your craft.

Mastering technical writing is a journey, but with practice and empathy for your audience, you can transform your documentation into a tool that empowers and enlightens its readers. Keep writing, keep improving, and most importantly—keep caring.

References

  1. Google Technical Writing
  2. Reddit: Becoming a Technical Writer
  3. SheCodeAfrica: A Guide to Technical Writing