word-list.md

0, 1, 2, 3, 4, 5, 6, 7, 8, 9

Use when the content refers to a lot of numbers. General rule: spell out in letters all numbers from zero to nine and use numerals for larger numbers.

air-gap, airgap

Use air-gap.

almost always

Use to ...

See also: most always.

below

Recommended: The table below ... Recommended: In the figure below, ... The table below shows ...

bespoke

Avoid.

Use custom.

blog/post

Refer to the collection of postings as a blog.

Individual entries are not blogs.

Better: Post an entry to your blog.

bug

See also: issue.

chart

See also: graph, table.

code

See also: program.

composed of

Use when every member is listed.

See also: consists of, includes

comprised of

Avoid.

consists of

Use when every member is listed.

See also: composed of, includes

copy and paste/copy-and-paste

could

See also: might.

dead

Avoid.

Use unresponsive to mean that a device or service fails to respond.

See also: unresponsive.

denote

e.g.

Avoid.

Replace with "for example, ... ."

Because "for example" indicates a partial list, it is redundant to add "etc." at the end of a list.

dialog

duration

Use to mean the time since a request or an event.

See also: time period.

etc.

Avoid.

either/or

female

Avoid unless technical adjectival.

Replace with "woman."

fix

See also: bug, resolve.

flag

For gflags, the flag is how it's used, not what it is. Use option to refer to what something is, and the flag is an implementation detail.

See also: option.

for example

Because for example implies a partial list, do not add, etc., to the end of any list.

go to

Use to tell a user to open a web page.

See also: navigate, visit.

i.e.

Avoid.

Replace with "that is, ... ."

font

includes

Use when the list of included members is incomplete.

See: consists of, composed of.

graph

See also: chart, table.

guide

See also: manual.

how-to

issue

See also: bug.

log in, log-in, login

Note: log on is less common, so avoid.

log into

log on

Mac

macOS

manual

See also: guide.

may, might

• "might" is the past tense of "may"

might

See also: could, may.

migrate

most always

Avoid.

Use almost always.

See also: almost always.

multiply

See also: times.

one, two, three, four, five, six, seven, eight, nine

Use when numbers are not heavily used in writing. Technical documentation almost always refer to lots of numbers and numerals, and multiplies them. So, using 0 to 9, instead of spelling them out, is preferable.

See also: 1, 2, 3, 4, 5, 6, 7, 8, 9.

open

See also: go to, navigate, visit.

option

See also: flag, parameter, setting, value.

or later

Examples: RHEL 7 or later.

Users tend to talk about the latest version of a product, not the newest.

or newer

Avoid.

page

See also: topic.

pane

panel

parameter

prioritize

Avoid.

Use rank. [plain English]

See also: rank.

program

See also: code.

purpose-built

reference

revert

See also: undo.

role

See also: user.

rolling upgrade

section

See also: page, topic.

send

setting

See also: flag, option, parameter, value.

should

Use to mean "ought to."

submit

that

See also: which.

therefore

See also: thus.

they

thus

See also: therefore.

time period

See also: duration.

times

See also: multiply.

topic

See also: page, section.

tutorial

undo

See also: revert.

unresponsive

update

upgrade

us

user

See also: role.

using vs. with

value

See also: flag, option, parameter, setting.

visit

Avoid.

Use go to.

See also: navigate.

we

Avoid.

Use you instead. Write as if you are talking to the user, not collaborating with them.

See also: you.

which

See also: that.

will

Avoid.

Use active voice instead of future tense.

Example: "The dialog appears" rather than "The dialog will appear"

would

you

Use you to speak to the reader.

See also: we.