DEV Community: Natália Kováč

Editing numbered steps so readers never lose their place

Natália Kováč — Fri, 13 Nov 2026 10:54:19 +0000

Numbered steps look like the easy part of a tutorial. But readers move back and forth between the page and their screen at every step, and that's where they lose their place. A step that hides two actions, or a warning that comes after the click, sends them back to reread.

When I edit a procedure, I read it as someone with one eye on the page and one on the screen. These are the edits I make most often.

One action per step

A step should be one thing the reader does before looking back at the page. When I see "and then" in a step, or two commands, I split it. The list gets longer, but ten short steps are easier to follow than five crowded ones, because the reader always knows which number they're on.

Condition first, then the action

"Click Delete, but only if you've exported your data first" is in the wrong order. By the time the reader reaches the condition, they may have clicked already. I move the condition or context to the front: "If you've exported your data, click Delete." Location works the same way: "In the Settings panel, select Notifications."

Say what the reader should see

Most steps stop at the action. I add a short line saying what should happen: a message appears, a file is created, a new tab opens. That's how readers know the step worked, and how they notice a problem right away instead of several steps later. If the writer isn't sure what the result looks like, nobody has checked.

Commands get their own code block

A command buried in a sentence is hard to copy and easy to mistype. Each command gets its own code block, with the prose before it saying what it does and after it saying what to expect.

Move optional paths out of the steps

"Alternatively, you can..." in the middle of a step forces a decision while the reader is busy following. If there are two real paths, such as cloud and self-hosted, I split them into two procedures or put the choice before step 1. Optional extras go in a note after the last step.

Use the same verb for the same action

Click, hit, tap, choose, pick: when a page mixes them, readers wonder if they mean different things. I agree on a small set, for example click for buttons, select for menu options, enter for typing into a field, press for keys, and match interface labels exactly, in bold.

Before and after

Here's a typical draft:

1. Clone the repository and install the dependencies with `npm install` and then start the server with `npm run dev`.
2. Hit **Save**, or alternatively press Ctrl+S if you prefer, and if you're on the cloud version skip to step 5.

And the same steps after editing. On the real page, the commands would be fenced code blocks; here they're indented so the example stays readable:

1. Clone the repository and open its folder in a terminal.

2. Install the dependencies:

       npm install

   When it finishes, the project has a `node_modules` folder.

3. Start the development server:

       npm run dev

   The terminal shows the local address where the app is running.

4. In the app, click **Save**.

   A "Saved" message appears at the top of the page.

The cloud path from the old step 2 moved out of the list entirely, into its own short section.

A quick check for crowded steps

A small script helps me find steps worth a second look. It flags numbered lines with more than one "and" or more than one inline code span:

import re
import sys

STEP = re.compile(r"^\s*\d+\.\s+(.*)")
CODE = re.compile(r"`[^`]+`")

with open(sys.argv[1], encoding="utf-8") as f:
    for number, line in enumerate(f, start=1):
        match = STEP.match(line)
        if not match:
            continue
        text = match.group(1)
        ands = len(re.findall(r"\band\b", text, re.IGNORECASE))
        commands = len(CODE.findall(text))
        if ands > 1 or commands > 1:
            print(f"line {number}: {ands} x 'and', {commands} code spans")
            print(f"  {text.strip()}")

Save it as check_steps.py and run it with the file name:

python3 check_steps.py tutorial.md

It only reads the first line of each step and can't tell a list of things from two actions, so it points me to places to look, not fixes. On the draft above, it flags step 1.

The last check: follow the steps yourself, looking at the screen after each one. If you have to search the page to find where you were, that step needs another edit.

Editing the 'Before you begin' section so readers don't get stuck at step three

Natália Kováč — Tue, 10 Nov 2026 09:09:01 +0000

When a reader gets stuck at step three of a tutorial, the problem is often not step three. It's the "Before you begin" section, which promised the reader was ready when they weren't. They installed the wrong version, or they don't have the right permission, or the tutorial assumed they knew something it never mentioned.

Prerequisites are usually written last and edited least. I've learned to give them a full editing pass of their own. Here's what I look for.

Vague items that can't be checked

A typical first draft looks like this:

## Prerequisites

- Node.js
- Docker
- A GitHub account
- Basic knowledge of the command line

Every item is true, and almost none helps. Which Node.js version? Does Docker need to be running, or just installed? What does the GitHub account need to be able to do? And "basic knowledge" means something different to every reader.

My test for each item: could a reader find out, in under a minute, whether they meet it? If not, the item needs editing.

Versions: give a number and a way to check

If the tutorial depends on a minimum version, say so, and show the command that prints it:

node --version

If the writer doesn't know the minimum, I ask them to note the version they tested with. "Tested with Node.js 20" is honest and still useful: readers on an older version know where to look first.

Installed is not the same as ready

Some tools can be installed but not usable. Docker is the classic case: the command exists, but the daemon isn't running, and the reader only finds out halfway through. A better check tests the thing the tutorial actually needs:

docker info

If Docker isn't running, this fails straight away with an error about not being able to connect to the daemon. That's much kinder at the top of the page than at step three.

Accounts and permissions

"A GitHub account" hides two questions: is the reader signed in where the tutorial needs them to be, and do they have permission to do what the steps ask? If a step creates a repository in an organisation or adds a secret, the reader needs more than an account.

Where a command exists to check this, I include it. For the GitHub CLI:

gh auth status

For local permissions, on Linux, a reader can check whether they're in the docker group, which is what lets them run Docker without sudo:

groups

When there's no command, I ask the writer to name the role or permission exactly, using the same words the interface uses, so readers can find it in their settings.

Assumed knowledge: name it and link it

"Basic knowledge of the command line" doesn't tell anyone whether they qualify. I replace it with the specific things the tutorial expects readers to do without explanation: change directories, set an environment variable, edit a file in a terminal editor. Then I link one good introduction for readers who need it. They can decide for themselves, and nobody feels tested.

Before and after

Here's the same section after editing:

## Before you begin

You'll need:

- **Node.js 20 or later.** Check with `node --version`.
- **Docker, installed and running.** Run `docker info`. If you
  see an error about connecting to the daemon, start Docker first.
- **A GitHub account with permission to create repositories**
  in the organisation you'll use. Check you're signed in to the
  GitHub CLI with `gh auth status`.
- **Comfort with a few terminal basics:** changing directories,
  setting environment variables, and editing a text file.

It's longer. It's also something a reader can work through like a checklist, and each line either passes or tells them what to fix.

Test it from a clean start

The final check isn't an edit at all. I ask someone who didn't write the tutorial to follow the prerequisites on a machine that isn't already set up, or in a fresh container or virtual machine. Writers have everything installed already, so they can't see what's missing. A clean setup shows it in minutes.

When a reader gets stuck now, I check this section first. Most of the time the fix is one more line in it.

Editing headings in docs for readers who scan

Natália Kováč — Sat, 07 Nov 2026 11:01:13 +0000

Most people don't read documentation from top to bottom. They land on a page, scan for the part that matches their problem, and read only that. The headings are what they scan. When I edit a docs page, I treat the headings as a separate piece of writing, and I edit them before I touch a single paragraph.

Read the headings on their own first

My first pass ignores the body text completely. I pull out just the headings and read them as a list, like a table of contents. For a Markdown file, I use a short Python script (more on it below), but copying them into a scratch file by hand works too.

Then I ask one question: if this list were all I saw, could I find the section I need? Here's a typical list from an install guide before editing:

Overview
Prerequisites
Install on macOS
  Verify the install
Configuration
  Advanced
Troubleshooting

It's not terrible, but "Overview", "Configuration" and "Advanced" don't tell a scanning reader much. Advanced what? Configuration of which part?

Name the task, not the category

Category labels like "Configuration" or "Usage" describe what kind of content sits underneath. Task headings describe what the reader can do with it. Readers arrive with a task in mind, so task headings match what they're looking for.

Some edits I make often:

"Configuration" becomes "Set your API key and default region"
"Usage" becomes "Run your first sync"
"Advanced" becomes "Use a proxy server"

The edited headings are longer. That's fine. A heading that is a few words longer but tells me exactly what's below saves more time than it costs.

Put the distinctive words first

When people scan, they mostly read the start of each line. If five headings in a row begin with "How to", the eye has to travel past the same two words every time to find the difference.

So I move the words that tell sections apart to the front:

"How to configure logging" becomes "Configure logging"
"Information about rate limits" becomes "Rate limits and how to stay under them"
"Steps for upgrading from version 2" becomes "Upgrade from version 2"

Starting with the verb or the key noun means the first word or two already identify the section.

Keep parallel headings parallel

Headings at the same level under the same parent are siblings, and readers compare them. If one sibling is a verb phrase, one is a noun and one is a question, the list feels uneven and harder to scan.

Before:

Installing on Linux
Windows
How do I install on macOS?

After:

Install on Linux
Install on Windows
Install on macOS

The edited version is a little repetitive, and that's the point. The repetition makes the one word that differs stand out.

Use the reader's words for problems

Troubleshooting sections are where headings matter most, because readers arrive with an error on their screen. A heading like "Path issues" makes them guess. A heading that quotes what they see, such as "command not found" after installing, lets them match it instantly, and it's also the text they're likely to search for.

A small script to list headings

This is the script I use for the first pass. It prints every H2 to H4 heading with its line number, indents by level, skips fenced code blocks (where # usually starts a comment), and marks a few headings I almost always end up rewriting:

import re
import sys

VAGUE = {"overview", "introduction", "general", "details", "notes",
         "miscellaneous", "other", "more information", "advanced"}

in_code = False
with open(sys.argv[1], encoding="utf-8") as f:
    for number, line in enumerate(f, start=1):
        if line.startswith("`" * 3):
            in_code = not in_code
            continue
        match = re.match(r"(#{2,4}) (.+)", line)
        if in_code or not match:
            continue
        level, text = len(match.group(1)), match.group(2).strip()
        flag = "  <- vague" if text.lower() in VAGUE else ""
        print(f"{number:>4}  {'  ' * (level - 2)}{text}{flag}")

Running python3 headings.py install.md on the guide above gives:

   2  Overview  <- vague
   4  Prerequisites
   5  Install on macOS
   9    Verify the install
  10  Configuration
  11    Advanced  <- vague
  12  Troubleshooting
  13    "command not found" after installing

The flag list is mine and deliberately short. A heading like "Overview" isn't always wrong; the flag is a prompt to check, not a verdict. The script also doesn't handle indented code blocks or headings written with underlines, which I rarely see in the docs I edit.

When to stop

I stop editing headings when the list on its own reads like a useful map of the page. Then I go back to the paragraphs, and often find that a clearer heading has already shown me which paragraphs belong somewhere else.

Editing code samples in documentation: what I check before they ship

Natália Kováč — Thu, 05 Nov 2026 11:46:48 +0000

When I edit a page of documentation, I used to skim past the code blocks. They looked technical, someone had presumably tested them, and my job was the prose around them. That was a mistake. The code samples are often the only part of a page a reader actually uses. Many people jump straight to the first grey box, copy it, and paste it into a terminal. If it fails, the clear paragraph above it doesn't help much.

So now code samples get an editing pass of their own. Here is what I check.

Can it be copied and run as is?

This is the first question, and the answer is "no" more often than you'd think. The usual problems are small:

A shell prompt ($ or >) at the start of each line, which gets pasted along with the command
Command and output mixed in one block, so the reader copies both
A step that depends on something the page never mentioned, like being in a certain folder
Curly quotes that crept in when the text passed through a word processor

The fix for the first two is the same: keep commands and output in separate blocks. Put the command in a block marked as bash, and the output in a block marked as text, introduced with a short line like "You should see something like this:".

Are placeholders obvious?

A sample like git clone https://example.com/project.git is fine as long as readers know which part to replace. When they don't, they either paste it unchanged or guess. I ask writers to use one style for placeholders across the whole set of docs, for example <your-project-name>, and to say right after the block what each placeholder means.

The angle brackets have a useful side effect. If someone pastes the line without replacing them, the shell treats < as a redirect and the command fails straight away, instead of quietly doing the wrong thing.

Does the text match the code?

Prose and code drift apart. A paragraph says "set timeout to 30" while the block below sets timeout: 60, because someone updated one and not the other. I read each sample next to the sentence that introduces it and check names, values and file paths line by line. It's slow and boring, and it catches something more often than I'd like.

Is it the shortest sample that works?

Long samples hide the point. If a page explains one configuration option, the reader doesn't need forty lines of unrelated settings around it. I suggest cutting to the lines that matter, and saying in the text that the rest of the file stays as it is.

Let a script do the dull part

In a docs-as-code setup, the pages are Markdown files in a repository, so some of these checks can run automatically. This small Python script finds every bash or sh block in the files you give it, flags lines that start with a $ prompt, and asks bash -n to check the syntax without running anything:

import re
import subprocess
import sys
from pathlib import Path

FENCE = re.compile(r"^```

(\w+)\s*\n(.*?)^

```\s*$", re.MULTILINE | re.DOTALL)

def check_file(path):
    text = path.read_text(encoding="utf-8")
    problems = 0
    for match in FENCE.finditer(text):
        lang, code = match.group(1), match.group(2)
        if lang not in ("bash", "sh", "shell"):
            continue
        line = text.count("\n", 0, match.start()) + 1
        if re.search(r"^\s*\$ ", code, re.MULTILINE):
            print(f"{path}:{line}: prompt '$' inside a copyable block")
            problems += 1
        result = subprocess.run(["bash", "-n"], input=code,
                                capture_output=True, text=True)
        if result.returncode != 0:
            print(f"{path}:{line}: syntax error\n{result.stderr.strip()}")
            problems += 1
    return problems

total = sum(check_file(Path(p)) for p in sys.argv[1:])
print(f"{total} problem(s) found")
sys.exit(1 if total else 0)

Save it as check_samples.py and point it at your docs:

python3 check_samples.py docs/*.md

On a test page with a prompt in one block and an unclosed if in another, it reports:

docs/install.md:3: prompt '$' inside a copyable block
docs/install.md:7: syntax error
bash: line 3: syntax error: unexpected end of file
2 problem(s) found

The line numbers point to the opening fence of each block. The script exits with status 1 when it finds something, so it can run as a step in CI and fail the build.

It won't tell you whether a command does the right thing, only that it parses. That still matters: a sample that can't even be parsed is one nobody tested.

Then run them for real

The last check is the one no script replaces. Before a page goes out, I follow it from top to bottom in a fresh terminal, copying every block exactly as a reader would. Whatever breaks is an edit, even if the prose around it is perfect.

Tables in documentation: when they help and when they get in the way

Natália Kováč — Sat, 31 Oct 2026 10:08:45 +0000

Tables are one of the first things I look at when I edit documentation. Sometimes a table is the clearest part of a page. Other times it's where the page falls apart: cells full of paragraphs, a column nobody needs, or a sequence of steps forced into rows.

Here is how I decide whether a table should stay, and what I change when it does.

A table is for comparing

A table works when the reader wants to compare several items across the same set of attributes. Plans and their limits, configuration options and their defaults, API parameters and their types. The reader's eyes move across a row or down a column, and the grid makes that easy.

| Option    | Type    | Default | Description                         |
|-----------|---------|---------|-------------------------------------|
| `timeout` | integer | `30`    | Seconds to wait before giving up.   |
| `retries` | integer | `3`     | How many times to retry on failure. |
| `verbose` | boolean | `false` | Print each request to the console.  |

Every row answers the same questions in the same order. That's the test I use: if the rows don't share the same columns naturally, it probably isn't a table.

Steps don't belong in a table

A common pattern is a table with "Step" and "Action" columns. It looks organised, but it adds nothing a numbered list doesn't already do, and it's harder to read on a narrow screen. Lists also give each step room for a short note or a code block, which a table cell handles badly.

1. Open **Settings** and select **API keys**.
2. Select **Create key**.
3. Copy the key and store it somewhere safe. It's only shown once.

Keep cells short

If a cell needs more than a sentence or two, the content usually belongs somewhere else. I move longer explanations into the text below the table, or into a separate section, and keep the cell to a short summary. A table full of paragraphs forces the reader to scroll sideways or read text squeezed into a narrow column.

Many Markdown flavours, including GitHub Flavored Markdown, don't support lists or multiple paragraphs inside a table cell anyway, which is a useful hint.

Make the headers do the work

Column headers are where the reader looks first, and some screen readers announce them together with each cell. So I make them specific:

Put units in the header, not in every cell: Timeout (seconds) instead of 30 seconds in each row.
Match the name used in the code or on screen. If the setting is called retries, the header doesn't say "Attempts".
Avoid empty headers. A blank first header above a column of names makes the table harder to follow when it's read aloud.

Don't leave cells empty

An empty cell can mean "no", "not applicable", "unknown" or "someone forgot". The reader has no way to tell which. I write the actual answer, such as "None", "Not supported" or "Not applicable", and I use the same wording throughout the table.

Order the rows on purpose

Alphabetical order is fine when the reader is looking something up by name. When most readers only need two or three rows, I put those first, or I split the table into "common options" and "advanced options". Either way, I want the order to be a choice, not whatever order the rows were added in.

Watch out for pipes and alignment

Two small Markdown details catch people out. A literal pipe character inside a cell breaks the column structure unless it's escaped, even inside inline code in GitHub Flavored Markdown:

| Operator | Meaning    |
|----------|------------|
| `a \| b` | a or b     |

And colons in the separator row control alignment. Numbers are easier to compare when they're right-aligned:

| Plan  | Users | Storage (GB) |
|:------|------:|-------------:|
| Free  |     1 |            5 |
| Team  |    10 |          100 |

One last test

My last step is to read one row from left to right and ask whether it makes sense as a sentence: "The timeout option is an integer, defaults to 30, and sets the seconds to wait." If a row can't be read that way, the columns are probably mixing different kinds of information, and the table needs another edit.

Editing changelogs so people can actually use them

Natália Kováč — Thu, 29 Oct 2026 10:08:29 +0000

Changelogs are a strange kind of document. Almost everyone who uses a project reads them at some point, usually right before an upgrade, and usually in a hurry. Yet they're often written last, quickly, and by copying commit messages into a list.

When I edit a changelog, I try to read it as the person who has to decide whether to upgrade today. Here's what I look for.

Commit messages are not changelog entries

A commit message is written for the people working on the code. A changelog entry is written for the people using it. The two overlap, but not much.

To see what changed since the last release, I start with the commit list:

git log --oneline v1.4.0..HEAD

This shows every commit after the v1.4.0 tag, one per line. It's raw material, not the changelog. Lines like fix typo, refactor parser, or bump deps may matter to contributors, but most users don't need them. What I want are the changes a user would notice: something new, something that behaves differently, something that stopped working, or something that got fixed.

Group by what the reader needs to do

A flat list of twenty items makes the reader do the sorting. I prefer the grouping from the Keep a Changelog convention: Added, Changed, Deprecated, Removed, Fixed, and Security. Even if a project doesn't follow that convention fully, the headings answer the questions people actually have.

## [1.5.0] - 2026-10-29

### Added
- Export to CSV from the Reports page.

### Changed
- Dates in exported files now use the YYYY-MM-DD format.

### Fixed
- Search no longer ignores words with accents.

Anything under Changed or Removed deserves a second look, because that's where upgrades break.

Lead with the effect, not the code

Here's a typical entry before editing:

- Refactored date handling in exporter module

And after:

- Dates in exported files now use the YYYY-MM-DD format.
  If you parse exports with a script, update the date format there.

The first version describes work that was done. The second describes what the reader will see, and what they might need to do about it. I ask myself one question for each entry: if this were the only line someone read, would they know whether it affects them?

Make breaking changes impossible to miss

A breaking change hidden in the middle of a list is the most expensive mistake a changelog can make. I move these to the top of the release section and mark them clearly, so nobody has to search for them:

### Removed
- **Breaking:** the `--legacy-output` option is gone.
  Use `--format=v1` for the old output.

The replacement goes right next to the removal. "Removed X" on its own leaves the reader with a problem; "Removed X, use Y instead" gives them a way forward.

Use the same words as the interface

If a button says "Export", the changelog says "Export", not "download", "save as file" or "data dump". Readers search changelogs for the words they see on screen or type in the terminal. Keeping the names identical makes those searches work, and it matches the rest of the docs.

Date and order consistently

Two small rules save a lot of confusion. First, newest release at the top. Second, one date format everywhere. I use YYYY-MM-DD because it doesn't mean different things in different countries, and it sorts correctly as plain text.

A quick read before it ships

My last check is simple. I read only the section headings and the first few words of each entry. If that skim tells me what changed and whether I need to act, the changelog does its job. If I have to read every line to find the one breaking change, it goes back for another edit.

Writing alt text for screenshots in documentation

Natália Kováč — Tue, 27 Oct 2026 10:06:02 +0000

Screenshots are everywhere in software docs, and most of them have alt text like screenshot, image, or the original file name. Sometimes there's none at all. When I edit a guide, the images are often the last thing anyone has looked at closely.

Alt text matters more in docs than people think. Screen reader users hear it instead of seeing the image. It shows up when an image fails to load, for example on a slow connection or after someone renames a folder in the repo. And it's text, so it can be searched and translated, which a picture of text can't.

Here's how I approach it.

Ask what the screenshot is for

Before writing anything, I ask one question: why is this image here? In docs, the answer is almost always one of these:

It shows where something is (a button, a menu, a field).
It shows what you should see after a step, so the reader can confirm it worked.
It shows a specific value or setting the reader has to match.
It's decoration, and the surrounding text already says everything.

The alt text should carry that purpose, not a full inventory of the screen. A settings page might have thirty controls on it, but if the step is about one checkbox, that checkbox is what the alt text is about.

Describe the state, not the pixels

Compare these two:

![Screenshot of the settings page](images/settings.png)

![The Notifications tab with "Email me when a build fails" turned on](images/settings.png)

The first tells me nothing I couldn't guess. The second tells me exactly what the screen should look like after the step, which is the whole reason the screenshot exists.

A few habits that help:

Skip "image of" and "screenshot of". Screen readers usually announce that it's an image already. Start with the content.
Use the exact UI labels, with the same capitalisation as the interface. If the button says "Save changes", the alt text says "Save changes", not "the save button".
Include values that matter. If the reader needs to pick "UTF-8" or set a timeout to 30, put that in the alt text.
Keep it to a sentence or two. If you need more, the information probably belongs in the body text.

Don't hide instructions in the image

This is the problem I find most often. A step says "Configure the options as shown below", and the actual settings only exist in the screenshot. Anyone who can't see the image, or whose image didn't load, is stuck.

The fix isn't longer alt text. It's moving the information into the step itself:

3. In **Format**, select **CSV**, and in **Encoding**, select **UTF-8**.

   ![The Export dialog with CSV and UTF-8 selected](images/export.png)

Now the step works without the image, and the screenshot becomes a confirmation. The alt text can stay short because the text above it does the heavy lifting.

When empty alt text is right

Not every image needs a description. If a screenshot only repeats what the text already says, or it's a decorative banner, an empty alt is the honest choice. In Markdown that's ![](images/banner.png), which renders as alt="". Screen readers generally skip images with empty alt text instead of reading out the file name.

The difference between "empty on purpose" and "forgot to write it" is invisible in the source, though. In repos I work on, I like a short HTML comment next to deliberate ones, so the next editor doesn't "fix" it:

<!-- decorative, text above covers it -->
![](images/banner.png)

A quick check before review

To find the obvious problems in a docs folder, I use a single grep. It looks for three patterns: empty or generic alt text, alt text that is a file name, and alt text that starts with "image of" or "screenshot of".

grep -rniE \
  -e '!\[(image|screenshot|picture|img)?\]\(' \
  -e '!\[[^]]*\.(png|jpe?g|gif|webp)\]' \
  -e '!\[(an? )?(image|picture|screenshot|photo) (of|showing)' \
  docs/

-r searches the folder recursively, -n adds line numbers, -i ignores case, and -E enables extended regular expressions. Each -e adds one pattern. On a test file it prints something like:

docs/setup.md:3:![](images/settings.png)
docs/setup.md:5:![screenshot](images/login.png)
docs/setup.md:7:![Screenshot 2026-03-02 at 10.14.png](images/export.png)
docs/setup.md:11:![image of the dashboard](img/dash.png)

It's not a verdict. The empty alt on line 3 might be deliberate, and the check can't tell whether a real description is accurate. It only catches images written in Markdown syntax, not HTML <img> tags. But it gives me a list to work through, which beats scrolling every page looking for images.

Keep it in sync

The last thing: alt text goes stale with the UI. When a button gets renamed and someone updates the screenshot, the alt text often keeps the old label. When I review a docs change that touches an image, I read its alt text against the new screenshot. It takes a few seconds, and it's usually the only place the old wording survives.

Writing alt text for screenshots in documentation

Natália Kováč — Sun, 25 Oct 2026 10:14:12 +0000

Here's how I approach it.

Ask what the screenshot is for

Before writing anything, I ask one question: why is this image here? In docs, the answer is almost always one of these:

It shows where something is (a button, a menu, a field).
It shows what you should see after a step, so the reader can confirm it worked.
It shows a specific value or setting the reader has to match.
It's decoration, and the surrounding text already says everything.

Describe the state, not the pixels

Compare these two:

![Screenshot of the settings page](images/settings.png)

![The Notifications tab with "Email me when a build fails" turned on](images/settings.png)

The first tells me nothing I couldn't guess. The second tells me exactly what the screen should look like after the step, which is the whole reason the screenshot exists.

A few habits that help:

Skip "image of" and "screenshot of". Screen readers usually announce that it's an image already. Start with the content.
Use the exact UI labels, with the same capitalisation as the interface. If the button says "Save changes", the alt text says "Save changes", not "the save button".
Include values that matter. If the reader needs to pick "UTF-8" or set a timeout to 30, put that in the alt text.
Keep it to a sentence or two. If you need more, the information probably belongs in the body text.

Don't hide instructions in the image

The fix isn't longer alt text. It's moving the information into the step itself:

3. In **Format**, select **CSV**, and in **Encoding**, select **UTF-8**.

   ![The Export dialog with CSV and UTF-8 selected](images/export.png)

Now the step works without the image, and the screenshot becomes a confirmation. The alt text can stay short because the text above it does the heavy lifting.

When empty alt text is right

<!-- decorative, text above covers it -->
![](images/banner.png)

A quick check before review

grep -rniE \
  -e '!\[(image|screenshot|picture|img)?\]\(' \
  -e '!\[[^]]*\.(png|jpe?g|gif|webp)\]' \
  -e '!\[(an? )?(image|picture|screenshot|photo) (of|showing)' \
  docs/

-r searches the folder recursively, -n adds line numbers, -i ignores case, and -E enables extended regular expressions. Each -e adds one pattern. On a test file it prints something like:

docs/setup.md:3:![](images/settings.png)
docs/setup.md:5:![screenshot](images/login.png)
docs/setup.md:7:![Screenshot 2026-03-02 at 10.14.png](images/export.png)
docs/setup.md:11:![image of the dashboard](img/dash.png)

Keep it in sync

Editing error messages: what happened, why, and what to do next

Natália Kováč — Fri, 23 Oct 2026 09:11:01 +0000

When I edit documentation, the error messages are often the part nobody asked me to look at. They live in the code, not in the docs folder, so they slip past review. Yet they are probably read more carefully than any page I edit, because the person reading one is stuck and wants to get unstuck.

Over time I've ended up with a simple test for any error message. It should answer three questions, roughly in this order:

What happened?
Why did it happen, if we know?
What can the reader do now?

Most weak messages answer only the first one, and some don't even manage that.

A before and after

Here's the kind of message I see a lot:

Error: invalid input

Invalid how? Which input? The reader now has to guess, search, or read the source. A rewrite using the three questions:

Couldn't save the project: the name "my project!" contains a character
that isn't allowed. Use only letters, numbers, hyphens and underscores,
for example "my-project".

It's longer, but every part does a job. The first clause says what failed. The middle names the actual cause and repeats the value the reader typed, so they can see the problem instead of hunting for it. The last part gives a rule and an example they can copy.

Say what failed in the reader's terms

Messages written from inside the code tend to describe the code. "NullReferenceException in ProjectService" is useful in a log, but the reader didn't do anything to a ProjectService. They clicked Save. So the message should start from the action they took: "Couldn't save the project".

If you need the technical detail for debugging, keep it, but put it after the human part or in a "details" section. Nobody should have to read a stack trace to find out their file is too big.

Don't blame, don't joke

"You entered an invalid date" and "That date isn't in a format we recognise" carry the same information. The second one doesn't point a finger. It's a small edit, and it makes a difference to someone who is already frustrated.

I'm also wary of jokes and cute phrasing in errors. "Oops, something went sideways!" might be charming the first time. The fifth time, when you've lost your work, it's grating. Plain and calm reads better under stress.

Make the next step concrete

"Please try again" is only good advice if trying again actually helps. If the fix is to change something, say what and how. If the reader can't fix it, say who can or where to look. A few patterns I reach for:

Give the allowed format with an example: "Use YYYY-MM-DD, for example 2026-03-14."
Name the setting or file: "Check the timeout value in settings.json."
Point to a specific docs page, not the docs home page.

A small code example

Even in a short script you can make an error helpful. Compare a bare failure with this:

from pathlib import Path


def load_config(path):
    config_file = Path(path)
    if not config_file.exists():
        raise FileNotFoundError(
            f"Couldn't find the config file at {config_file.resolve()}. "
            "Create it by copying config.example.toml "
            "into the same folder."
        )
    return config_file.read_text(encoding="utf-8")


load_config("config.toml")

Run it without a config.toml and the last line of the traceback reads:

FileNotFoundError: Couldn't find the config file at /home/you/app/config.toml. Create it by copying config.example.toml into the same folder.

Printing the full resolved path is the detail I like most here. A surprising number of "file not found" problems turn out to be "the script was looking in a different folder than I thought", and the absolute path makes that obvious in one glance.

Collect them in one place

The most useful editing trick I know for error messages is to stop reading them one at a time. If a project keeps its messages in a single file, or you can pull them out with a quick search, read them all together in a list. Inconsistencies jump out right away: "Couldn't" in one place and "Unable to" in another, "folder" next to "directory", some messages ending with a full stop and some without. Pick one of each and apply it everywhere.

Then do one last check: trigger a few of the errors yourself and read them in context, on the screen where they actually appear. A message that reads fine in a list can be cut off in a narrow dialog, or show up somewhere the reader won't notice it. That's still part of the edit.

Six small edits that make technical docs easier to follow

Natália Kováč — Wed, 21 Oct 2026 17:55:01 +0000

A lot of documentation is technically correct and still hard to use. The information is there, but the reader has to work to get it out. Most of the time the fix isn't a rewrite. It's a handful of small, repeatable edits.

These are the ones I make most often when I edit docs, READMEs and how-to guides.

1. Put the goal before the instruction

Readers scan for the thing they want to do. Make that the first thing they see.

Before:

Run npm run build -- --analyze if you want to see which packages make the bundle large.

After:

To see which packages make the bundle large, run npm run build -- --analyze.

Same words, but the reader can now decide in the first few words whether the sentence is for them.

2. One action per step

Numbered steps that hide three actions in one step are where people get lost.

Before:

Create a .env file, add your API key and restart the server.

After:

Create a file called .env in the project root.

Add your API key: API_KEY=your-key-here

Restart the server.

More steps, but each one is easy to finish and easy to come back to if something goes wrong.

3. Say what success looks like

After an important step, tell the reader what they should see. Otherwise they don't know whether to continue or start debugging.

Run docker compose up. When the setup works, the last line of the output is Server listening on port 3000.

This one edit removes a lot of "is it supposed to do this?" questions.

4. Put conditions and warnings before the step

If a step only applies in some cases, or can break something, say so before the command, not after it.

Before:

Run make reset-db. This deletes all local data.

After:

Warning: the next command deletes all local data. Run make reset-db.

People copy and paste. By the time they read the sentence after the command, it has already run.

5. Define a term the first time, then stick to it

If you call something a "workspace" in one section, a "project" in the next and an "environment" later, readers will assume these are three different things. Pick one word, explain it briefly the first time it appears, and use it consistently. A short glossary helps if the docs use many specialised terms.

6. Cut "simply", "just" and "easy"

"Simply configure the proxy" is fine for the person who already knows how. For everyone else it adds a small sting: if it's simple and I'm stuck, the problem must be me. These words rarely add information, so removing them costs nothing.

A quick way to apply these

When I edit a doc, I do one pass per edit instead of trying to fix everything at once:

Read only the headings and first sentences. Is the goal always up front?
Read only the numbered steps. One action each? Success described?
Search for "simply", "just" and "easy".
Search for every key term and check it's used the same way.

Each pass is quick, and doing them separately means I actually notice the problems instead of skimming past them.

None of this needs a tool or a style guide. It just needs someone to read the doc as a person who has never seen the project before. If you can, ask a new teammate to follow your guide while you watch. You'll find the confusing step within minutes.

What edits do you find yourself making again and again in docs?