Grammar and word choice

Choose words that preserve the intended meaning and make the sentence easy to follow. A shorter synonym helps only when it means the same thing. Remove, extract, and delete can describe different operations; glyph is necessary vocabulary for a type designer.

Name the actor and action

Use present tense for current behavior and an imperative for an instruction. Keep past tense when describing a documented earlier state, and future tense when timing matters. Passive voice is useful when the actor is unknown or irrelevant: “The connection was interrupted.” It should not conceal who changes a document or where work is stored.

An instruction such as “Choose a folder” names an action. “You can choose a folder” describes an available choice. Keep can when that distinction matters. Likewise, be and have are ordinary verbs, not defects to remove: “The folder is empty” states a useful fact.

Use because for a cause when since could mean either time or cause. Distinguish if, which introduces a condition, from when, which locates an event in time. Do not change one to the other merely to vary the wording.

Keep modifiers close

Place only beside what it limits. “Export only the selected glyphs” limits the set of glyphs. “Only export the selected glyphs” can imply that exporting is the sole permitted action. Rephrase if either reading remains possible.

Break a long noun chain into its relationships. “The settings for exporting variable fonts” is easier to follow than “variable font export configuration settings.” Keep an established technical compound when the intended audience knows it.

A modifier must refer to the right subject. “After selecting a glyph, the panel opens” implies that the panel selected the glyph. Write “After you select a glyph, the panel opens,” if that is the documented behavior.

Words ending in -ing can name a task, object, or state. A heading such as “Updating settings” might mean instructions for an update or a process already underway. Use “Update the settings” for a task and “Update settings” for the settings themselves.

Make references unambiguous

Replace it, this, or they with a noun when more than one referent fits. “Move the layer into the group, then rename it” leaves the object of the second action unclear. Name either the layer or the group.

Keep articles, relative pronouns, and prepositions when they clarify structure. “Select the files that you want to export” is easier to translate than a compressed sequence of nouns. Ending a sentence with a preposition is acceptable when the alternative is awkward.

Do not force every language to repeat the English pronoun you. English voice measurements describe English prose. A translation uses its own grammar and forms of address; see localization review.

Use contractions where they read naturally

Ordinary contractions such as don't, can't, and it's suit most house prose. Expand one when emphasis, clarity, or a specified controlled language requires it. Avoid an ambiguous contraction such as the app's when the reader could mistake is for possession. Do not manufacture contractions from product names.

Use it's for it is or it has and its for possession. Apostrophes do not make ordinary plurals: write APIs, fonts, and 1990s. Preserve the exact spelling of identifiers even when the surrounding sentence is plural: Glyph objects, not Glyphs unless that is a different API name.

Define unfamiliar terms in context

Use one preferred term for each concept within a product. Explain a specialist meaning when the reader might know only the ordinary meaning. A master in a font project, for example, needs the font-design definition; replacing it with an unrelated generic synonym would obscure the subject.

Explain an unfamiliar abbreviation on first use if it recurs. If it appears once, the full term is usually sufficient. Familiar forms such as PDF and USB need no ceremonial expansion for an audience that knows them. Choose a or an by the intended pronunciation, not by the written first letter.

For general English prose, prefer for example and that is to e.g. and i.e.. Preserve conventional Latin phrases, quotations, and technical notation when they carry a necessary meaning. Do not add an abbreviation merely to shorten a sentence.

Choose the destination's English spelling convention and apply it consistently. Preserve published names, quoted labels, code, and exact input. A spelling check must not convert a product label into a different label.