Archive:Docs Project Style Guide - Word usage, capitalization, and spelling

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
(Created page with "'''%''' <br />See percent. '''24x7''' <br />See also ''time''. '''3-D''' (n. or adj.) '''a.m.''' <br />Lowercase with periods and a preceding space. '''above''' <br />...")
 
(Added categories)
Line 718: Line 718:
  
 
'''ZIP code'''
 
'''ZIP code'''
 +
 +
[[Category:Docs Project]]
 +
[[Category:Documentation]]

Revision as of 20:33, 22 August 2012

%
See percent.


24x7
See also time.


3-D (n. or adj.)


a.m.
Lowercase with periods and a preceding space.


above
Do not use to refer to information mentioned previously. When documents are converted to another format or layout, the information may no longer be “above.”

acronyms
Spell out acronyms or initialization before using them in text, e.g., “Embedded DevKit (EDK).” Unless the acronym or initials stand for a proper noun, use sentence case for the spelled-out version, e.g., “central processing unit (CPU).”

To form the plural of an acronym, add a trailing, lowercase s with no apostrophe, e.g., ROMs, PINs.

affect
When you affect something, it produces an effect.

alpha release
Do not capitalize this, as in "the alpha release of Product Foo."

alternate
Do not use this to mean “an alternative to something.” “Alternate” is a verb that means to change between two states or options. As an adjective, it means every second (alternating) thing in a series. If you mean “another way or option,” use “alternative.”

and/or
Avoid if possible. One or the other nearly always conveys the real meaning. If it doesn’t, try a structure like, “Have some bacon, eggs, or both.”

applications
When used as a proper name, use the capitalization of the product or project, such as GNUPro, Source-Navigator, and Red Hat Enterprise Linux. When used as a command, use lowercase as appropriate, such as “To start GCC, type gcc.”

Note: “vi” is always lowercase.

assure
Assure suggests mental comfort. Example: “I assured my future father-in-law that I would eventually find a job.” Also see ensure and insure.

auto-detect

Autofs

backport

back end (n.); back-end (adj.)

back up (v.); backup (n.); back-up (adj.)

backtrace

backward
Avoid using “backwards” unless you are stating that something has “backwards compatibility.”

backwards compatibility

bandwidth

basically
Do not use. For example, removing the word “basically” in the following sentence strengthens it: “This is how it is basically done.”

because
Do not use “since” to mean “because.” Use “because” to refer to a reason. Use “since” to refer to the passage of time.

below
Do not use to refer to information mentioned “below.” When documents are converted to another format or layout, the information may no longer be “below.”

BIOS
Plural: BIOSes

big data
Descriptive term, not a proper noun, so not capitalized.

bit rate

Boolean

boot disk

boot loader

Bps, bps
Bits per second is abbreviated bps. Bytes per second is abbreviated Bps. Also see bandwidth.

Britain
The language is English, and the place is the United Kingdom of Great Britain and Northern Ireland, aka the UK. Using Britain/British is usually wrong and to some implies a specific subjective statement about the state of Northern Ireland.

bug fix

built-in

bulleted lists
Lists should always consist of more than two items. Use bullets for a list in which the order of items is unimportant. Use a numbered list only when the order is important, as in a series of steps.

can/may
Use “can” to describe actions or conditions that are possible. Use “may” only to describe situations where permission is being given.

cannot

canceled

capitalization
If it’s not the official name of a real product or service, don’t capitalize it. Not even if it seems important. Capitalize only the first letter of the first word in headlines, titles, subtitles, and other call-out text.

cd or CD
When referring to the change directory command, use cd. When referring to a compact disk, use “CD.” The plural is “CDs.”

checkbox

chipset

ciphertext

client side (n.); client-side (adj.)

cloud
Use a lowercase “c” when referring to cloud or cloud computing in a general sense.

combo-box

commas Use serial commas. A serial comma is the comma before the “and” in a series of three or more items: “Item 1, item 2, and item 3.” Because in some cases it is necessary to use a serial comma to avoid confusion, it is best to always use it for consistency. An exception to this rule is in press releases, where it is traditional and preferred not to use serial commas.

comma-delimited (adj.)

command-driven (adj.)

command language, line, processor

contractions
Avoid when writing policy manuals or other more formal types of manuals. Contractions may also cause problems for documents that are translated, so avoid them in global content.

control character

control key
Use Ctrl instead, such as “To save the program, press Ctrl+Z.”

control program

cross-site scripting

cross-platform

currency
Use the following format: $1,500 USD, omitting “USD” if it is clear that it is in US currency.

daisy chain

dashes
When possible, use em-dashes (—) with no space on either side. When full em-dashes aren’t available, use double-dashes with no spaces on either side--like this.

datacenter

data mirroring

data type

datasheet

debug

denial of service (DoS)

dialog box

different
Use “different from” rather than “different than.”

disc, disk Compact disc, but diskette or hard disk.

double-click

downtime
The period during which a server, service, or other resource is unavailable.

download

dual-boot

DVD writer
Do not use DVD burner or CD burner (use CD writer in that case).

e-book, e-business, e-commerce, e-learning

earlier
See later.

Emacs

email

effect
See affect.

email

ensure Ensure means “to make sure.” Also see assure and insure.

'essentially Do not use. Also see basically.

Ethernet

exclamation points (!) Do not use them at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command.

Exif

ext3

extranet

failover (n.); fail over (v.)

fault tolerance

Fedora™ Project

fiber
Despite the alternative spelling used in Fibre Channel, “fiber” is the correct form to use in all other cases.

Fibre Channel

file name

file system

FireWire

firmware

floating point

forward
Avoid using “forwards.”

front end (n.); front-end (adj.)

FTP
Stands for file transfer protocol. You may actually need to refer to SFTP, secure file transfer protocol. Use lowercase when referring to the command-line program.

g++ or G++
When referring to the command, use g++. When referring to the program, use G++.

gas or GAS
When referring to the command, use gas. When referring to the program, use GAS.

GB

Gbps

gcc or GCC
When referring to the command, use gcc. When referring to the program, use GCC.

gcj or GCJ
When referring to the command, use gcj. When referring to the program, use GCJ.

gdb or GDB
When referring to the command, use gdb. When referring to the program, use GDB.

gigabyte
2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. Abbreviated “GB.”

GIMP (GNU Image Manipulation Program)

GNOME

GNU
(GNU’s Not UNIX)

GNUPro

gray

GTK+

hard-coded (adj.); hard code (v.)

hard copy
Do not use. Instead, use “printed.”

hard disk

hard drive

he/she
Do not use. Reword to avoid.

high-availability (adj.); high availability (n.)

high-performance computing (HPC)

homepage

host group

hostname
Capitalize when used at the beginning of a sentence, but try to reword the sentence to avoid this.

hot add

hot plug

hot swap

hotline

HTML

Hyper-Threading

hypervisor

Hz
Also see bandwidth.

I/O

i.e. and e.g.
i.e. means “in other words.” e.g. means “for example.” Add commas after each (e.g.,).

illegal
Illegal means “prohibited by law,” not “incorrect” or “not permitted.” You may be looking for the word “invalid.”

in concert with
Do not use. Instead, simply say “with.”

Infrastructure-as-a-Service (IaaS)

inline

insecure
Do not use “nonsecure,” “non-secure,” or “unsecured.”

installation program Do not use “installer.”

insure
“Insure” relates to monetary insurance. Also see assure and ensure.

Intel 64
Do not use “Hammer,” “x86_64,” or “x86-64” as the name of this architecture. The correct term for AMD’s implementation of this architecture is “AMD64.”

interesting
Avoid using, as this is a substitute for showing the reader why something is of interest. For example, change “It is interesting to note” to “Note.”

Internet

intranet

IP (Internet Protocol)

IPsec (Internet Protocol security)

is designed to
Avoid this and similar phrases when describing a function.

Incorrect: SSH is designed to work with almost any kind of public key algorithm or encoding format.

Correct: SSH works with almost any kind of public key algorithm or encoding format.

just
Use sparingly and avoid when possible. For example, in a phrase like, “Just point your browser to,” omit the word “just.”

KB

kbps

kernel space (n.); kernel-space (adj.)

kilobit, kilobyte

later/newer
When referring to more recent versions of a product, package, or other software, use “later.” When referring to earlier versions, use “earlier.”

left-click

life cycle

Linux®
Linux is a registered trademark of Linus Torvalds. It gets a registered trademark symbol on first use.

lists
Keep the structure of bulleted lists equivalent and consistent. If one bullet is a verb phrase, they should all be verb phrases. If one is a complete sentence, they should all be complete sentences, etc.

Capitalize the first word of each bullet, unless it is obvious that it is just a list of items, such as a list of items like: computer monitor keyboard

When the bulleted list items complete a sentence or are sentences themselves, use periods on each item. If they do not, or are simply a list of items (like the list above), no periods are necessary.

log file

log in (v.); log-in (adj.); login (n.)

lookup (n.); look up (v.); look-up (adj.)

LVM

man page

mashup

may/can
Use “can” to describe actions or conditions that are possible. Use “may” to describe situations where permission is being given.

MB; Mb
MB is short for megabyte (1,000,000 or 1,048,576 bytes, depending on the context). Mb is short for megabit.

MBps

metadata

Microsoft
Do not use “MS”, “MSFT” or “MicroSoft.”

months
Abbreviate months and states according to AP. Months are abbreviated only if they are used in conjunction with a day. Example: “The President visited in January 1999.” or “The President visited Jan. 12.” Abbreviated months: Jan., Feb., March, April, May, June, July, Aug., Sept., Nov., Dec.

Mozilla Firefox
Subsequent references can be “Firefox.”

Mozilla Thunderbird
Subsequent references can be “Thunderbird.”

multi-
Hyphenate words with the prefix “multi” unless the dictionary or this guide says otherwise.

multiprocessing

MySQL

nameserver

namespace

.NET

newer

non-
Hyphenate words with the prefix “non” unless the dictionary says otherwise.

nonsecure
Use “insecure” instead.

NULL or null
When a command or value is stated, use NULL. When stating that something is null, use “null.”

numbers
Write out numbers between one and nine.

Exceptions:

  • Beginning a sentence
  • Preceding another number (four 6-pound bags)
  • Approximations (“thousands of”)
  • Very large values (4 billion)
  • Ranges (4—6 datacenters)

Use numerals for numbers 10 and greater, negative numbers, fractions, percentages, decimals, measurements, references to book sections (Chapter 3, Table 5, Page 11), and numbers less than 10 if they appear with numbers of 10 or greater (“You answered 8 out of 14 questions correctly”). Also use numerals when referring to code (such as x = 6) and release versions (Fedora 18).

numbered lists
Lists should always consist of more than two items. Use bullets for a list in which the order of items is unimportant. Use a numbered list only when the order is important, as in a series of steps.

Objective C

object-oriented

OEM (original equipment manufacturer)

offline

online

on-site
Hyphenated when used as an adjective, as in “on-site labs.”

on demand (adv.); on-demand (adj.)

opcodes

open source

operating system

orientate
Do not use. A user becomes “oriented” to an environment.

over
When referring to something quantifiable, use “more than” instead.

override

packet-switching

pc or PC
When referring to program counter, use pc. The first instance must have the acronym defined, such as “program counter (pc).” When referring to a general computer, use “PC.”

percent (%)
Use the percent sign (%) whenever referring to numerical percentages. Example: In a survey, 60% of users said they were satisfied with their technology solution. Exception: Press releases and press blogs follow strict AP style, which spells out 'percent' in all uses.

peer-to-peer architecture

Perl

plain text

Platform-as-a-Service (PaaS)

please
Do not use. Instead of “Please refer to the Getting Started Guide,” write, “Refer to the Getting Started Guide.”

plug-in (n); plug in (v)
As a noun, “plug-in” is a hardware or software module that adds a specific feature or service to a larger system.

p.m.
See a.m.

pop-up

PostScript

PowerPC
Do not use “PPC” or variants.

PPP

proximity
Don’t use “close proximity.” It’s redundant.

pseudo-ops

pulldown

quotations
“Place the punctuation inside the quotes,” said the editor. Except in rare instances, use only “said” or “says” for quotes. Other words liked “noted” or “quipped” get in the way of the quote itself and tend to editorialize.

Place “said” first, followed by the name: “Friends, freedom, features, first,” said Beefy Miracle.

regardless
“Irregardless” is not a word.

read-only

read/write

real-time (adj.); real time (n)

reboot

recursive

Red Hat
Write “Red Hat.” Not “Red Hat, Inc.” (The only exceptions to this rule are when the company itself is writing legal or financial statements.) “Red” and “Hat” should be on the same line together. Don’t let them be separated by a line break.

Pronoun and verb agreement: A company is singular in the US. In other words, Red Hat is an “it,” not a “they.”

right-click

roadmap

RPM

runlevel

runtime

screenshot

scrollbar

SELinux

server side (n.); server-side (adj.)

set up (v.); setup (n.); set-up (adj.)

sign up (verb), sign-up (noun, adjective)

shut down (v.)

simply
Do not use. See basically.

since
See because.

smart card

soft copy
Do not use.

Software-as-a-Service (SaaS)

sound card

space
Use when referring to white space, such as “Ensure there is a space between each command.” Use “spacebar” when referring to the keyboard key.

spaces (using)
Use only one space between sentences. Use no spaces around an em-dash.

spec file

standalone

startup

states
Use the two-letter postal abbreviations. See stateabbreviations.us for a list.

stovepipe

subdirectory

submenu

superuser

swap space

SysV

taskbar

Telnet

that/which
“That” introduces a restrictive clause — a clause that must be there for the sentence to make sense. A restrictive clause often defines the noun or phrase preceding it.

“Which” introduces a non-restrictive, parenthetical clause — a clause that could be omitted without affecting the meaning of the sentence. Use”who” or “whom,” rather than “that” or “which,” when referring to a person.

For example: The car was travelling at a speed that would endanger lives. The car, which was travelling at a speed that would endanger lives, swerved onto the sidewalk.

that vs. who Use "that" when referring to places and things, including groups (e.g., customers), teams, and companies. Use "who" when referring to individual persons.

then/than
“Then” refers to a time in the past or the next step in a sequence.
“Than” is used for comparisons.

third-party

this
The word “this” can be used as an adjective or a pronoun. If you use it as a pronoun, be clear what the antecedent is. If it is unclear, use the adjective form by following “this” with a noun.

throughput

time zone

timeout

token-ring

toolbar

troubleshoot

under
When referring to something quantifiable, use “fewer than.”

UNIX
UNIX is a registered trademark of The Open Group. Do not use “UNIX-like.” Use an expression like “Linux, UNIX, and similar operating systems” instead.

upgrade

URLs
For URLs that begin with http://www., you may omit that portion and give the main URL, such as fedoraproject.org. If it begins with ftp or https, you should include the full URL.

US (adjective), United States (noun)

usable

userid

user interface

username

user space

utilize
Avoid this term. Write “use” instead.

vi, Vim

virtualization

Web 2.0
Avoid using this term.

web, web browser, webmaster, web server, website

white space

whitepaper

workflow

worldwide

writable

x86

Xen

X Window System

ZIP code