Write for someone

I find “make this clearer” easier to work with once I can name the person reading it. A teammate reviewing a change and someone encountering the project for the first time need different amounts of context.

Start with what brought them here. If they need to decide whether to try a prototype, tell them what it does and what you want them to look at. The history of how it was built can wait until it explains something they need to know.

Compare “We have implemented improvements to the document management experience” with “You can now rename a document without opening it.” The second sentence lets someone picture the change. Familiar words help, but the specific action does most of the work.

What does the next sentence add?

Every additional piece of information can create another question. A caveat may resolve an important uncertainty; an unexplained acronym may introduce one. I want each sentence to earn the attention it asks for.

Shorter is not automatically clearer. A button labelled “Remove” needs more context if the action permanently deletes a shared file. Keep the words that help someone understand the consequence.

Read the draft without relying on what you already know. Check what “this” refers to, whether the main point arrives early enough, and whether the reader knows what to do next. For a proposal, that usually means making the decision easy to find.

The same question applies to an interface: what does someone need to understand at this moment?