Language Proficiency — Precise Words, Clear Sentences

One Nightjar page says "probe", another says "check", and the dashboard says "ping". A careful reader asks the obvious question: are these three different things? They are not. Loose language made a simple product look complicated, and the reader paid for it with confusion.

The rule

One term per thing, and every sentence shows who does what.

Language proficiency for a technical writer is less about fancy vocabulary and more about precision. Four habits carry most of the weight:

• Consistent terms. Pick one word for each concept and use it everywhere. Nightjar's word is check, so "probe" and "ping" go. Record the choice in a word list so every writer and reviewer follows it.
• Active voice. Name the actor. "Nightjar sends an alert" tells the reader who acts. "An alert is sent" hides it, and the reader may wonder whether they are meant to send it.
• Clear references. Every "it", "this" and "they" must point at exactly one noun the reader can see.
• Plain, literal words. Prefer "use" to "utilise" and "start" to "initiate". Skip idioms like "out of the box" or "a piece of cake": readers working in a second language, or through a translation tool, may take them literally.

Grammar and punctuation still matter. They are rarely noticed when right, but each error makes a reader trust the page, and the product, a little less.

Here is a sentence from the old alerts page, and its repair:

Before: Once the incident has been opened, it will be sent to the verified channels, and it can be muted.

After: When an incident opens, Nightjar sends an alert to every verified alert channel. You can mute the incident from the dashboard.

The shortcut

Ask "Who does what?" of every sentence. Point to the actor and the action. If you cannot, rewrite.

The trap is "elegant variation": swapping in synonyms to avoid repeating a word, as school essays reward. In technical writing, repetition is a feature. A new word signals a new thing.

Drills

Answer fast — trust the rule.

Remember

• One term per thing, and every sentence shows who does what.
• Shortcut: ask "Who does what?" of each sentence and rewrite when you cannot point to both.
• Trap: elegant variation; in docs, a new word signals a new thing.