Clear technical writing: actions, conditions and checks

A good instruction helps someone perform an action and check the result. A good project description explains the challenge, the author's role and the current status. A shorter text is useful only when it retains the information the reader needs.

In this practice, I combine plain language, ASD-STE100 technical-writing principles and William Zinsser's approach. These are editorial foundations, not a claim that the site's texts conform to ASD-STE100. Its controlled English vocabulary and grammar rules cannot be transferred mechanically to Russian or other languages.

Start with the reader's task

Before editing, answer three questions: who needs the text, what should they understand and what should they be able to do afterwards? For an intern, explain the tool's name. An experienced specialist may need only a short checklist.

Instead of “Check the request in DevTools”, give the steps for the selected browser: “In Chrome on Windows, press F12. Open the Network tab. Repeat the action on the page and find the request.” Then state which field or value to check. Interface names can change; verify them against the version in use.

Name the action and the person responsible

“The settings are checked” does not say who checks them or what they check. Use: “Before starting, the administrator checks the service address and the account's permissions.” For an instruction, use a direct command: “Check the service address.”

An instruction usually contains one action. Put any condition that changes the sequence before the action: “If the request fails, save the error code. Then check the log.” Keep the condition even if it makes the sentence longer.

Use consistent terms

Choose one name for each entity. If the interface calls it “Meeting room”, use that name in the next steps too. Explain a technical term the first time it appears, then use it consistently.

A link should name the document or the expected result. “API documentation” is more useful than “here”. Preserve code, paths, identifiers and button names exactly. Do not rewrite them for style.

Separate the role from the outcome

When describing experience, show what you did, what the team did and what remains in progress. “I clarified the requirements and helped change the architecture. The team implemented the main workflows” keeps the contributions clear.

A rollout plan is not a completed rollout. Do not present planned scope as an achieved result. If you use a fictional image or metaphor, identify it and give a factual account alongside it.

Plan for translation

English, German and Spanish share the same goals: readers can find what they need, understand the conditions and see the next step. Use each language's natural grammar. Do not copy Russian sentence structure word for word.

Avoid phrases whose meaning depends on a local joke or idiom. Keep product terminology, version numbers and links consistent. Check label lengths: German navigation often needs more space. Plain language for a broad audience and formal easy-language systems serve different purposes.

Check the text through an action

Give the instruction to someone who does not know the task. Ask them to find the step and explain the result. Record their questions. If they understand the words but do not know what to do, clarify the content as well as the wording.

A project description needs a different check: can the reader name the challenge, your role and the status without further explanation? If not, revise those parts first.

Sources

The site's editorial rules are based on the author's supplied guide, “Clarity as a Working Tool”, dated 3 October 2026.