What Makes Good Documentation - and why it matters for both humans and AI

I have worked in technical roles for a long time now, across different teams, tools, and levels of chaos. The pattern that never changes though is this:

If your documentation is poor, everything else is harder than it needs to be.

Whenever something goes wrong in a business, the instinct is usually to blame the person who carried out the task.

  • A form was filled in wrong.
  • The wrong template was used.
  • A student was enrolled on the wrong course.
  • A client was emailed the wrong update.

In those moments, I always come back to the same question:

Can you honestly blame the person, or should you be blaming unclear, outdated, or completely missing documentation?

If the process is written well, most people will follow it. If the process is vague or scattered across three different places, they will guess. When people guess, you get inconsistency, rework, and occasionally, full-on drama.

Exactly the same is true when you work with AI.
If you ask AI to do something and it gets it wildly wrong, it is easy to blame the model. But was your instruction actually clear, specific, and realistic enough?

  • “Write me a proposal” vs
  • “Write a 500-word proposal for a local college, aimed at Heads of Department, explaining how our AI workshop will help their staff design smarter lesson plans.”

The second one will always win, for humans and for AI.

Good documentation is the shared brain of your organisation. It underpins SOPs, process documents, instructions, technical guides, handovers, onboarding, and all those little “how we do things here” moments that usually live inside someone’s head until they leave.

So, here is a practical guide to writing documentation that actually works in the real world.

1. Start With The Real Job To Be Done

Before you open a document, ask one simple question:

“What decision or action should this help someone take?”

If you cannot answer that, the documentation will drift.

Examples:

  • “Help a new starter log into all the core systems on day one.”
  • “Help a tutor record attendance correctly for every session.”
  • “Help a support agent refund a customer without needing to ask a manager.”

Once you have that clarity, everything else becomes easier. You are not writing “a document”, you are designing a tool.

Quick rule:
If someone could read your documentation from top to bottom and still not know what they are supposed to do, it is not finished.

2. Make It Ridiculously Easy To Skim

Most people will not read your document in order. They are scanning for the one line that solves their problem. Write for that behaviour.

2.1 Use clear, descriptive headings

Headings are not decoration. They are the main navigation system.

  • Bad: Overview
  • Better: How to reset a student's password

Ask yourself: if someone is quickly scrolling, would this heading make them stop?

2.2 Put a simple table of contents at the top

Nothing fancy. Even just:

  • Logging in for the first time
  • Resetting your password
  • What to do if you are locked out

This makes a long document feel smaller and less stressful.

2.3 Use short paragraphs

Huge blocks of text hide important details. Keep paragraphs short, especially when describing steps, options, or exceptions.

If you have one important sentence, give it its own line. Let it breathe.

3. Lead With The Useful Bit

People should not have to wade through three paragraphs of context just to find the answer.

Whenever you can, start with the takeaway, then provide background.

Example:

  • Instead of:
    “From time to time you may find that a learner can no longer access their online resources due to issues with their account setup. In these situations, you will need to check our system and see what has gone wrong.”

  • Try:
    “If a learner cannot access their course, check these three things first:”

    1. Are they enrolled on the correct course?
    2. Has their account been activated?
    3. Has their password recently been reset?

The second version gives immediate value, then you can explain each step in more detail below if needed.

4. Write Like You Are Standing Next To Them

Good documentation should feel like a calm person talking you through a task, not a policy document scolding you from a distance.

4.1 Use simple, direct language

Avoid corporate fluff.

  • Instead of: “Leverage the platform to deliver enhanced learning outcomes.”
  • Try: “Use the quiz feature to check what learners understand at the end of each module.”

You are not dumbing it down. You are making it usable.

4.2 Use concrete actions

Focus on what to click, what to look for, and what to type.

  • Click New Course.
  • Choose Adult Learning.
  • Set the start date to the first teaching week.
  • Press Save.

People should be able to follow the document with the system open in front of them, step by step.

4.3 Explain “why” only where it helps

Context is valuable, but not everywhere. Add “why” when it helps someone make a better decision.

  • “Choose the nearest start date, because this controls when reminder emails are sent.”

That extra line prevents future confusion, without turning the document into a novel.

5. Treat AI Like A Very Literal Team Member

A lot of people now use AI to help them write SOPs, emails, lesson plans, and more. The quality of the output still depends on the quality of the instructions though.

If your documentation is clear, you can often reuse it directly as an AI prompt.

5.1 Bad AI-style instruction

“Write a handover for my client work.”

That gives AI too much freedom. You will get something that looks impressive, but does not actually match what you do.

5.2 Better AI-style instruction, built from documentation

“Write a handover for my client, summarising:

  • What we have delivered so far,
  • What is currently in progress,
  • What the client needs to do next,
  • Any risks or deadlines they should be aware of.

Use a friendly, professional tone, and keep it under 600 words.”

That structure is exactly the kind of thing you would put into a handover template for humans too.

Good documentation and good AI prompts share the same qualities: clear roles, clear objectives, and clear constraints.

6. Make It Visual, But Not Overwhelming

Some processes genuinely benefit from visuals.

  • A simple flow chart for “What to do when a payment fails”.
  • A screenshot showing the correct menu to click.
  • A timeline for a course launch.

Use visuals where they remove confusion, not just to fill space.

Tip: Always label screenshots with a short sentence like
“You should see this page after you click Submit.”
That way, if the interface changes slightly, the text still helps.

7. Keep Documentation Alive, Not Static

A document is not “finished” just because it exists.

7.1 Give each important document an owner

One person, not “the team”.

That person is responsible for:

  • Updating it when systems change,
  • Checking it still matches reality,
  • Retiring it if it is no longer needed.

7.2 Add a simple review rhythm

  • Critical processes: review every 3 months.
  • Regular processes: review every 6–12 months.
  • Anything involving regulation or safety: review whenever rules change.

7.3 Date the last update

Add this at the top:

  • Last updated: 03 Feb 2026 by Sam

It instantly tells readers how much to trust what they are seeing.

8. Practical Checklist: Before You Share Any Documentation

Before you publish or share a document, check:

  1. Purpose

    • Have I written the actual job this document is meant to support?
    • Would a stranger understand what this is for?

  2. Skimmability

    • Are the headings clear and descriptive?
    • Is there a simple contents section if the document is long?

  3. Clarity

    • Are the steps written in simple, direct language?
    • Could someone follow this with the system open in front of them?

  4. Order

    • Do I lead with the key takeaways and quick wins?
    • Are decisions and “if this, then that” moments obvious?

  5. Examples

    • Have I used straight-forward, relatable examples?
    • Would this still make sense to someone outside my department?

  6. AI-readiness

    • Could these instructions be copied into an AI prompt and still make sense?
    • Have I been specific about outcome, audience, and format?

  7. Maintenance

    • Is there a named owner and a last updated date?
    • Do we know roughly when it will be reviewed next?

If you can honestly tick those off, your documentation is already better than what most organisations are working with.

Final Thought

Good documentation removes excuses on all sides.

  • It stops people being blamed for processes they were never clearly taught.
  • It stops leaders assuming “we covered that in a meeting once” counts as clarity.
  • It stops AI from inventing its own version of your workflow just because you kept things vague.

When you make documentation skimmable, concrete, and kept in sync with reality, you are not just producing more paperwork. You are building a layer of trust and predictability into your organisation, for both humans and machines.