Randy A Brown

Category: Clarity & Systems Thinking

  • What Makes Documentation “Good”? (A Practical Checklist)

    What Makes Documentation “Good”? (A Practical Checklist)

    Reading Time: 3 minutes

    Most documentation isn’t terrible, but it can be hard to use.

    It might be accurate. It might even be complete. But if users can’t quickly find what they need and understand it without effort, it fails its purpose.

    Good documentation isn’t about volume or technical depth.

    It’s about helping people get things done correctly.

    This article gives you a practical checklist you can use to evaluate and improve any documentation you write.

    What “Good” Documentation Really Means

    Good documentation is:

    • Clear (easy to understand)
    • Usable (easy to follow)
    • Findable (easy to navigate)
    • Relevant (focused on the user’s goal)

    Users will struggle if any of these are missing.

    The Practical Checklist

    Use this checklist to review your documentation before publishing.

    1. Is the Purpose Clear?

    Can a reader quickly answer:
    “What is this, and why should I care?”

    • Is there a clear title?
    • Does the introduction explain the goal?
    • Is the outcome obvious?

    Good:

    “How to Install the App and Get Started”

    Weak:

    “Application Setup Notes”

    2. Is It Written for the Right Audience?

    • Does it match the reader’s skill level?
    • Are terms explained if needed?
    • Are assumptions kept to a minimum?

    Good documentation meets the reader where they are, not where the writer is.

    3. Is the Structure Easy to Follow?

    • Are sections logically organized?
    • Are headings clear and descriptive?
    • Can users scan the content?

    A good structure breaks up the text. Look for:

    • Short sections
    • Clear headings
    • Helpful bullet points

    If everything blends, users will get lost.

    4. Are the Steps Clear and Actionable?

    For instructional content:

    • Are the steps numbered?
    • Does each step contain one action?
    • Do steps start with strong verbs?

    Good:

    1. Open the app
    2. Click Settings
    3. Select Account

    Weak:

    Open the app and go to settings to change your account

    5. Is the Language Simple and Direct?

    • Are sentences easy to read?
    • Is jargon minimized or explained?
    • Are unnecessary words removed?

    Good documentation sounds natural, not robotic.

    6. Are Examples Included?

    Examples make abstract ideas concrete.

    • Are there real-world examples?
    • Do they match the reader’s context?

    Even one simple example can dramatically improve understanding.

    7. Are Key Details Highlighted?

    • Are warnings, notes, and tips included where needed?
    • Are important actions easy to spot?

    Look for:

    • Note: Helpful context
    • Tip: Shortcuts or best practices
    • Warning: Potential risks

    These guide users and prevent mistakes.

    8. Can Users Find What They Need Quickly?

    Ask yourself:

    • Can someone scan this and find the right section fast?
    • Are headings specific enough?
    • Is unnecessary content in the way?

    Good documentation respects the user’s time.

    9. Does It Show What Success Looks Like?

    After instructions, users should know:

    • What should happen next
    • What a correct result looks like

    Example

    After clicking Submit, you should see a confirmation message.

    This reduces uncertainty and builds confidence.

    10. Has It Been Tested?

    This is the most important, and most ignored, step.

    • Have you followed the instructions yourself?
    • Has someone else tested it?
    • Were there any points of confusion?

    If users struggle, the documentation needs improvement.

    A Quick Scoring Method

    To evaluate your documentation, rate each item from 1 to 5:

    • 1 – Needs major improvement
    • 5 – Excellent

    If most of your scores are:

    • 4–5 – You’re in good shape
    • 3 or below – Focus on improving those areas

    This gives you a simple, repeatable way to improve your work over time.

    Common Signs of Poor Documentation

    Watch for these red flags:

    • Long, dense paragraphs
    • Missing steps
    • Unexplained jargon
    • No clear structure
    • Outdated or inaccurate information

    If users frequently ask questions, your documentation likely needs work.

    Final Thoughts

    Good documentation doesn’t try to impress.

    It tries to help.

    If someone can quickly find what they need, understand it, and complete their task without frustration, then you’ve succeeded.

    Everything else is secondary.

  • A Beginner’s Guide to Writing Step-by-Step Instructions That Actually Work

    A Beginner’s Guide to Writing Step-by-Step Instructions That Actually Work

    Reading Time: 3 minutes

    Step-by-step instructions are at the heart of technical writing.

    But here’s the problem: most instructions look clear… until someone actually tries to follow them.

    Then things break down.

    • Steps are skipped
    • Assumptions are made
    • Users get stuck or frustrated

    Good instructions don’t just tell people what to do; they help people complete a task without confusion.

    Let’s walk through how to write instructions that actually work in the real world.

    1. Start with the Goal

    Before you write a single step, answer this:

    What should the user be able to do when they’re finished?

    Be specific.

    Weak goal:

    Set up the software

    Strong goal:

    Install the software and launch it for the first time

    This keeps your instructions focused and prevents unnecessary steps.

    2. Know Who You’re Writing For

    A beginner needs more detail than an experienced user.

    Ask:

    • Have they done this before?
    • Do they understand the tools involved?
    • What might confuse them?

    Example

    If your audience is new, don’t just say:

    Open the terminal

    Say:

    Open the terminal (on Windows, search for “Command Prompt” in the Start menu)

    Always write for the least experienced person you expect to read your instructions.

    3. List Prerequisites Up Front

    Nothing frustrates users more than getting halfway through and realizing they’re missing something.

    Include a short “Before you begin” section:

    • Required tools or software
    • Accounts or permissions
    • Files or downloads

    Example

    Before you begin:

    • Install Node.js
    • Have access to your project folder
    • Download the sample file

    This prevents unnecessary backtracking.

    4. Break the Task into Clear, Numbered Steps

    Each step should contain one action.

    Avoid this:

    Open the app and log in and click Settings

    Do this instead:

    1. Open the app
    2. Log in with your username and password
    3. Click Settings

    Numbered steps make it easy to follow and easy to recover if something goes wrong.

    5. Use Action-Oriented Language

    Start each step with a clear verb.

    Examples:

    • Click
    • Open
    • Type
    • Select
    • Enter
    • Run

    Weak:

    You will need to click the button

    Strong:

    Click Submit

    Be direct. Be clear. Be consistent.

    6. Be Specific (But Not Overwhelming)

    Clarity comes from the right level of detail.

    Too vague:

    Configure the settings

    Too detailed:

    Move your mouse to the top-right corner, carefully position it…

    Just right:

    Click Settings, then select Notifications

    Give enough detail to guide, not overwhelm.

    7. Show What Success Looks Like

    After important steps, tell the user what should happen next.

    Example

    Click Install

    You should see a progress bar. When the installation is complete, a “Success” message appears.

    This helps users know they’re on the right track.

    8. Include Warnings and Notes

    Help users avoid mistakes by calling out important details.

    Example

    Note: This action cannot be undone.
    Tip: Save your work before continuing.
    Warning: Make sure you select the correct file, or you may overwrite your data.

    These small additions can prevent big problems.

    9. Use Screenshots (When Helpful)

    Screenshots are especially useful when:

    • The interface is complex
    • The step involves multiple options
    • The user might click the wrong thing

    But don’t overuse them. Only include visuals when they add clarity.

    10. Test Your Instructions

    This is the step most people skip.

    Follow your own instructions exactly as written:

    • Don’t rely on memory
    • Don’t skip steps
    • Pretend you’re a beginner

    Even better: have someone else test them.

    If they get stuck, your instructions need improvement.

    A Simple Template You Can Use

    Here’s a basic structure for any set of instructions:

    Title: What the user will accomplish

    Before you begin:

    • Requirement 1
    • Requirement 2

    Steps:

    1. Step one
    2. Step two
    3. Step three

    Result:
    What the user should see or be able to do

    Common Mistakes to Avoid

    • Skipping “obvious” steps
    • Combining multiple actions into one step
    • Using vague language
    • Assuming prior knowledge
    • Not testing the instructions

    Final Thoughts

    Good instructions don’t just explain a process.

    They guide someone from confusion to success.

    If your reader can follow your steps without stopping, guessing, or getting frustrated, you’ve done your job.

  • How to Explain Technical Concepts to Non-Technical People

    How to Explain Technical Concepts to Non-Technical People

    Reading Time: 3 minutes

    If you can explain something technical to a non-technical person, you’ve mastered one of the most valuable skills in technical writing.

    This isn’t just about “dumbing things down.” It’s about clarity, empathy, and structure. Whether you’re writing documentation, blog posts, or training materials, your goal is simple:

    Help someone understand something they don’t currently understand without overwhelming them.

    Let’s walk through how to do that in a practical, repeatable way.

    1. Start with What They Already Know

    People understand new ideas by connecting them to familiar ones.

    Before you explain anything, ask:

    • What does my reader already understand?
    • What is this concept similar to?

    Example

    Instead of saying:

    “A database stores structured data in tables.”

    Say:

    “A database is like a digital filing cabinet where information is stored in organized folders (called tables).”

    You’re not changing the meaning; you’re building a bridge.

    2. Use Simple, Concrete Language

    Simplify. Technical writing often becomes confusing because it uses abstract or overly formal language.

    Replace this:

    • “Initialize the application” with “Start the app”
    • “Authenticate the user” with “Log in”
    • “Execute the command” with “Run the command”

    Simple language doesn’t make you sound less intelligent; it makes you more effective.

    3. Break Complex Ideas into Steps

    Non-technical readers struggle when too much information comes at once.

    Instead of explaining everything in a paragraph, break it into steps:

    Example

    How data moves through a system:

    1. You enter information into a form
    2. The system sends it to a server
    3. The server processes it
    4. The result is sent back and displayed

    Each step builds understanding gradually.

    4. Use Analogies (But Don’t Overdo Them)

    Analogies are powerful because they connect new ideas to familiar experiences.

    Good analogy:

    “An API is like a waiter in a restaurant. You tell the waiter what you want, they take your request to the kitchen, and bring back your food.”

    But be careful:

    • Don’t stretch analogies too far
    • Don’t mix multiple analogies in one explanation

    Use them to clarify, not complicate.

    5. Remove or Explain Jargon

    Jargon is one of the biggest barriers for beginners.

    You have three options:

    1. Remove it (best option)
    2. Replace it with simpler words
    3. Explain it immediately

    Example

    “You’ll need to configure the repository.”
    Becomes:
    “You’ll need to configure the repository (this just means setting it up the first time).”

    Never assume your reader knows the terms, even if they seem basic to you.

    6. Focus on the “Why,” Not Just the “What”

    Non-technical readers often don’t just want instructions; they want understanding.

    Weak explanation:

    “Click this button to deploy the app.”

    Better explanation:

    “Click this button to deploy the app (this makes your app live so others can use it).”

    A small addition like this makes a big difference.

    7. Use Examples Generously

    Examples turn abstract ideas into something real.

    Example

    Instead of:

    “Variables store values.”

    Say:

    “A variable stores a value. For example, you might store a person’s name like this:
    name = "John"”

    Even simple examples can unlock understanding.

    8. Write Like You Speak (But Stay Clear)

    Good technical writing sounds natural, not robotic.

    Too formal:

    “The user is required to input their credentials.”

    Better:

    “Enter your username and password.”

    Write like you’re helping someone sitting next to you.

    9. Anticipate Confusion

    Put yourself in the reader’s position:

    • What would confuse you if you were new?
    • What questions would you ask?

    Then answer those questions before they’re asked.

    Example

    “Install the package using this command.”
    You might add:
    “(If you’ve never used the command line before, don’t worry; we’ll walk through it step by step.)”

    This builds trust and reduces frustration.

    10. Test Your Explanation

    The best way to know if your writing works?

    Have a non-technical person read it.

    If they:

    • Ask questions
    • Get stuck
    • Misunderstand

    That’s valuable feedback, not failure.

    A Simple Framework You Can Use

    When explaining anything technical, follow this structure:

    1. Start with a simple definition
    2. Connect it to something familiar
    3. Break it into steps or parts
    4. Give an example
    5. Explain why it matters

    Final Thought

    The goal of technical writing isn’t to show how much you know.

    It’s to make things easier for someone else.

    If a complete beginner can read your explanation and say,
    “Oh, that makes sense now,”
    then you’ve done your job well.

  • The Top 5 Technical Writing Books on Amazon (And Why They Matter)

    The Top 5 Technical Writing Books on Amazon (And Why They Matter)

    Reading Time: 3 minutes

    Technical writing is one of the most valuable skills in today’s workplace. Whether you’re documenting software, writing procedures, or explaining complex ideas, the ability to communicate clearly can set you apart.

    If you’re serious about improving, the fastest way to level up is by learning from experts. Below are five of the best technical writing books on Amazon; trusted by professionals, recommended across multiple sources, and proven to deliver real results.

    This article contains affiliate links.

    1. Technical Communication — by Mike Markel

    Amazon

    If you want one book that covers everything, this is it.

    Often used as a college textbook, Technical Communication is widely considered the gold standard in the field. It walks you through:

    • Writing reports, manuals, and proposals
    • Understanding your audience
    • Designing documents for readability
    • Communicating in professional environments

    This book stands out for its balance of theory and real-world application. It’s especially helpful if you want a deep, structured understanding of technical writing.

    Best for: Serious learners, students, and professionals
    Downside: It’s dense, more like a course than a quick read

    2. Technical Writing 101 — by Alan S. Pringle

    Amazon

    If you prefer something practical and beginner-friendly, this is a great starting point.

    Technical Writing 101 focuses on what you actually need to do the job:

    • Planning and structuring documents
    • Writing clearly for non-technical audiences
    • Understanding workflows and tools
    • Preparing for a technical writing career

    It reads more like a guide than a textbook, making it ideal if you want actionable advice without academic overload.

    Best for: Beginners and career changers
    Downside: Less depth than academic texts

    3. Technical Writing Process — by Kieran Morgan

    Amazon

    This book focuses on one thing: process.

    Instead of overwhelming you with theory, it gives you a clear, repeatable system for creating documentation:

    1. Plan
    2. Research
    3. Write
    4. Review
    5. Publish

    Because it’s simple and structured, it’s one of the most consistently recommended technical writing books online.

    Best for: Freelancers and working professionals
    Downside: Not as comprehensive as larger textbooks

    4. Docs for Developers: An Engineer’s Field Guide to Technical Writing

    Amazon

    This is a modern, practical guide built specifically for developers and technical professionals.

    Unlike older writing-focused books, this one teaches how to create documentation in real-world environments like:

    • APIs and developer platforms
    • Open-source projects
    • Internal engineering documentation

    It emphasizes:

    • Writing for technical audiences
    • Creating useful, task-oriented documentation
    • Collaborating with teams
    • Maintaining docs over time

    What makes it stand out is its hands-on, example-driven approach, perfect for people who learn by doing rather than reading theory.

    Best for: Developers, engineers, and hands-on learners
    Why it’s valuable: Reflects how technical writing actually happens today

    5. The Insider’s Guide to Technical Writing — by Krista Van Laan

    Amazon

    This is the most career-focused book on the list.

    It goes beyond writing and explains:

    • What technical writers actually do
    • How documentation teams work
    • Tools, workflows, and industry expectations
    • How to break into the field

    It’s especially helpful if you’re considering technical writing as a career or want to understand how the profession works in real companies.

    Best for: Career insight and industry context
    Downside: Less focused on step-by-step writing instruction

    How to Choose the Right Book

    Each of these books serves a different purpose. Here’s a quick way to decide:

    Final Thoughts

    Technical writing isn’t about sounding smart; it’s about making things easy.

    The best writers aren’t the ones who use the most words. They’re the ones who remove confusion.

    If you read even one of these books and apply what you learn, you’ll already be ahead of most people in your field.

    What is your favorite book about technical writing?