Consistently following style guidelines as you write and edit will help you produce quality documents. While consistency is important as you edit your documents, readability should always be the main goal—even if it means having to break a rule.

It is very important to choose a style guide that works best in your particular industry. Our general technical focus means that, while we deviate in a few places, we refer to the Chicago Manual of Style. But some industries tend to refer to other guides: for example, the biotech industry tents toward the Council of Science editors (CSE) style guide.

While style guides differ, here’s the overarching rule: If you choose to commit a grammatical or typographical sin, then sin boldly and consistently!

General layout and style

Whether a document will be read online or in a printed book, consistent application of style rules is key to a quality reading experience. This presents some basic layout and style rules. Additional guidelines for documents that will be read on a screen are in the Document design for PDF section.

    • Acronyms and abbreviations On first use, spell out the phrase followed with the acronym in parentheses, then use the acronym throughout.

      Philip Glass Ensemble (PGE).

      If you use the acronym only one time in the document, then consider omitting it. Also, you can omit spelling out acronyms that are incredibly well known to your audience, such as RAM or CPU in a software API document. For more information, see Abbreviations.

    • Alignment In most types of documents, text should be left aligned. It is generally best not to “full-justify” text, as this may create odd spacing and hyphenation.

    • Bullets See Lists below.

    • Casing, capitalization Inconsistent capitalization will give your readers pause, making them wonder if there’s a reason for an unnecessarily capitalized word.

      • Capitalization of words Do not capitalize merely to emphasize words. Reserve capitalization only for proper nouns, which are the names of people, days, countries, companies, etc.

        The name of the item “signal multiplexer made by Acme” just uses normal words, but “the Acme Signal Multiplexer” uses a proper name.

        In software and electronics documentation, pay attention to capitalization of variable names, pin names, and signal names. They are official names and each one should be spelled and cased correctly.

      • Casing of headings and titles There are two general styles of capitalization used in headings and titles, sentence case and title case, as shown below. Choose one and use it consistently.

        (Sentence case) Case it exactly as you would a normal sentence: only capitalize the first word (and proper nouns): This sentence is sentence cased.

        (Title case) Capitalize every word except for articles (a, the), prepositions (to, in), and conjunctions of fewer than four letters (and, but): This Sentence is Title Cased.

        Another casing option is all caps, but AS IT COMES ACROSS AS YELLING, you should avoid it in most cases.

      • Casing in prefixes and symbols The rules vary wildly for some special cases, so your best bet is to find an authoritative resource that pertains to the industry for which you are writing. Also see Casing in acronyms.

        The prefix G (giga or billion) and M (mega or million) are upper case. The prefix k (kilo or thousand) is lower case. W (Watt) is always capitalized, including when combined with other letters, such as in kW.

        For an authoritative source regarding these and other prefixes, see the NIST Metric (SI) Prefixes page

    • Citations Inline or in footnotes, when referring to sources of information, put main titles, such as the titles of books or magazines, in italics. When applicable, set titles of individual magazine articles or book chapters in quotation marks. In all cases, follow the title by a comma then the name of the author set in regular text. When possible include a link to the source. Bibliographic lists generally place the author name (last name first) before the title. (More formal documents may require a more rigorous system of citations.)

      (Footnote): Collected Stories, “Barn Burning,” William Faulkner (1948)

      (Bibliography): Faulkner, William, Collected Stories, “Barn Burning” (1948)

    • Flow rules Different software tools have different names for this, such as keep, flow, or protect. As much as your tools allow, prevent page breaks or column breaks from separating headings from the text immediately following them. This also applies to table and figure names or captions.

    • Headings Heads, subheads, and inline heads are used to label content, making it possible for users to clearly understand the context of what they are reading and to efficiently “scan” through the document.

      • Heads and subheads Limit the number of levels to four or at most five. Set heads and subheads such that the size, color, and weight of the text will graphically inform the reader where they are in the hierarchy of the document. For example, the level-1 heading should be more prominent than the level-2 heading, the level-2 heading should be more prominent than the level-3 heading, and so on.

      • Inline heads Heads that precede content in a sentence, bullet, or paragraph are called inline heads. Inline heads, such as those used throughout this page, should be styled in such a way that clearly sets them apart from the following information, such as by bolding and following with a period. However you choose to style your inline heads, apply it consistently.

    • Hyperlinks Any item that is clickable should be set in a style that visually sets it apart from normal text without distracting the reader and affecting readability, such as by underlining or changing its color. The wording of hyperlinks should be active and inform the reader of either what will happen if the link is clicked (imperative verb-based link text), or what content the click will make available (noun-based link text). Whether verb- or noun-based, apply a consistent linking style.

      Verb-based link: Download the report.

      Noun-based link: Download the Music Review Report.

  • Hyphenation Many editors prefer to disable hyphenation for breaking words at the end of a line. If you allow hyphenation in your document, then use non-breaking hyphens to prevent line breaks in the middle of hyphenated words or names that you don’t want broken across lines. Also see non-breaking spaces in Space.

  • Lists

    • Bullets vs. numbers In lists where you have a set of related content, use bullets to delineate each item. Use numbers only if the specific order of the items is important.

    • Tone The items within a set should be written in a similar voice, tense, and structure.

    • Case and punctuation Use sentence case for each item and end with a period unless there are only one or two words per item.

    • Nesting Nest lists when necessary, using additional inset and a different bullet symbol or number style at each nesting level. Limit nested list levels to no more than two or, at most, three levels.

[ Back to the category list ]

Punctuation

Consistency is important, from casing your titles and positioning your page numbers, all the way down to whether you use the Oxford comma. Inconsistent punctuation calls attention to itself*, which will slow your readers down as they stumble along the path.

    • Ampersand (&) Only use the ampersand character as a last resort for space, low character counts (such as for social media), or when quoting material from others. Otherwise, spell out the word “and.” If you use the ampersand for stylistic reasons, be sure to apply it consistently. Never use an ampersand in a file name or email address.

    • Comma (,) In a series of words or phrases separated by commas, always use a comma before the conjunction. This is called the “Oxford comma” or the “series comma” and is sometimes a source of bickering between editors and writers. If you detest the Oxford comma, then don’t use it—but be consistent! In the following example, either this person has humorously named their dogs Grandma and Grandpa, or the sentence is missing a comma and the walk included their grandparents.

      I went on a walk with my dogs, Grandma and Grandpa.

    How to decide whether to use commas around parenthetical text or a qualifying clause: The text, if removed, should leave a grammatically correct sentence. “This sentence (the one you’re reading now) is an example.” → “This sentence is an example.”

      • Dashes There are three types of dashes normally used in writing: the hyphen, en dash, and em dash:

          • Hyphen (-) Use a hyphen to connect words into a single term. When a combination of words creates an adjective phrase, use hyphens where necessary to unambiguously convey meaning. When the meaning is clear without the hyphen, which is frequently the case with adverbs, then omit it. (Also see Hyphenation.)

            The phrase “centrally located vault” is clear without a hyphen.

            In the sentence, “The ancient history professor retired,” a hyphen is needed to indicate whether the retiree is a professor of ancient history (ancient-history professor), or is just old (ancient history-professor).

          • En (–) Use an en dash (not a hyphen) to indicate a range.

        This theory has 3–5 parts. (Although writing “3 to 5,” or even “three to five,” might be preferred in some cases.)

        Does the phrase “values from 23 to 25” include or exclude the 25? A specification document should clarify this with “from 23 to 25 inclusive” or “from 23 through 25.”

          • Em (—) Use an em dash, not a hyphen, to set a phrase apart with more of an interruption than would be created by commas. We suggest that you do not use a space before and after the dash, but whatever you do, apply it consistently.

        Philip Glass—likely as a result of his studies of Indian music—is known for subverting the traditional Western norms of composition.

      • Ellipse (…) The ellipse indicates a trailing thought and implies that there is additional content. Therefore, unless that is exactly what you intend to convey, reserve it for only very informal writing. There should be only three dots in an ellipse. If the ellipse appears at the end of a sentence, follow it with a period.

      • Period (.) Use at the end of a sentence and optionally after inline heads and at the end of bullets. Always place only one space after the period or other punctuation at the end of a sentence. (See more on this in Space below.)

      • Quotation marks (“”) Especially when writing for an American or global audience, place the terminating punctuation of a sentence inside the quotation marks:

        “This is a sentence.”

        If you are including quoted content inside a quote, then use single quotes (see example below). In this case, place the ending punctuation inside the quotation marks unless it is a nested quotation:

        I will sing “Let it Be.” “He was singing the song ‘Let It Be’.”

        Also see Citations in the General Layout and Style section above.

    Don’t use quotation marks gratuitously because they can imply that the “word” should be interpreted in a “different” way than it is normally understood. Your “readers” will probably find this “confusing.”

      • Slash (/)A slash has no universal interpretation. Don’t use/employ slashes when common words suffice. A slash often can be replaced with “and” or “or.”

    Sometimes there is no good substitute for “and/or.” Avoid it in legalese and use it in other contexts only when the sense is clear and after considering alternatives such as “A, B, or both,” or “A or B.”

    • Space

      • After punctuation Always place just one space after a period or other punctuation at the end of a sentence. The two-spaces rule is only applicable with non-proportional type such as with older typewriters or in code samples. (I know your teachers told you to use two spaces, but this is a case of incorrect information being passed along. Help spread the word: Only. One. Space!)

      • Indents For layout purposes, use a tab instead of multiples of spaces to indent text, with exceptions for computer code where the number of spaces may be significant.

      • With numbers and values See Space in the Math and numbers section.

      • Non-breaking space Use a non-breaking space to prevent a line break in the middle of a date (June 15), quantity (10 kg), name (Ms Smith), or anything else in which the line break would make the text harder to read.

    [ Back to the category list ]

    Globalization

    In today’s business environment, many documents are produced for a global audience. If you are producing documents intended for a local audience, then favor language choices appropriate for that locale. Otherwise, following are a few style decisions to make documents accessible across the world.

    • Articles Do not omit definite and indefinite articles (the, a, an). They make English sentences smoother and easier to read.

    • Dates Dates are written differently across the world. For this reason, you should spell out (or abbreviate) the month name.

      Rather than 11/12/20, write either Dec. 11, 2020 or 11 Dec., 2020.

    • Idioms and other phrases Avoid idiomatic phrases, such as sneak peek, by and large, deep seated, and for all intents and purposes. They may make sense to you, but idioms often do not translate well to a global audience and in extreme cases might confuse your readers.

      Replace “for all intents and purposes” with more direct words. Does it mean “always?” Or “for our needs?” Or “in effect?”

      Reserve the term “sea change” for describing a metamorphosis such as in Shakespeare’s The Tempest, from where the term originates. Consider simplifying it to “change” if that’s what you mean.

      Replace “in the event that” with “if.”

    • Measurements Some parts of the world use the metric system (centimeters, liters, etc.), while others use the imperial system (inches, gallons, etc.). Always show every measurement in both values. Which value you show first doesn’t matter, as long as you are consistent.

      27 cm (10.63 in)

    • Spelling Multinational corporations, worldwide consortia, and other organizations generally favor American English spelling for a global audience. This is reflected in the Word choice section below.

    • Time Some regions prefer a 24-hour clock, often referred to as “military time,” while others use a 12-hour clock that requires the use of am and pm (or AM and PM: just be consistent). The best choice depends not only on your audience but also on the type of document. Whichever method you choose, apply your standard consistently.

      Never use 12 am or 12 pm. The “am” stands for “ante meridiem” (before noon), while “pm” is “post meridiem” (after noon), so neither makes any sense: Noon is neither before nor after itself, and midnight is equally before and after noon, depending which day you consider. Use ”noon” or “midnight” instead. (Thank you to Jim Cownie (@JimCownie) for this nice wording.)

      Another consideration is the time zone. Every organization handles this differently, some using the time zone for their headquarters as their default. When in doubt, specify the time in some reasonable local time zone (such as your own location, or where the event is to be held) and give the UTC time as well, as shown in the example below. (My resource for figuring out the time across time zones is timeanddate.com.)

      “The meeting is at 2:00 pm Pacific (10:00 pm UTC)”

    • Word choice Many organizations favor American spelling and other conventions in globalized documents. See Word choice below for more information.

    [ Back to the category list ]

    Word choice

    Language evolves and writing style guides must evolve with it. Following are words that are commonly misused or misspelled. We include American English spelling for words so as to accommodate those writing for a global audience. See Globalization above for more information.

    Above almost all else, consistency is your most important guideline. For each technical concept or thing, choose one name and use it consistently. For example, if it’s introduced as a “ground braid,” then don’t refer to it as a “ground wire” later on.

    • affect, effect Use affect as a verb and effect as a noun.

      “I wanted to affect the timeline.”

      “The effect was brilliant.”

    • apropos Apropos does not mean “appropriate.” It means “in reference to.” Because it’s a confusing word, replace it with more common words.

    • assure, ensure, insure Use assure when you are convincing someone of something. Use ensure when you are making sure of something. Only use insure when talking about insurance.

      “I assure you that it will work.”

      “Save your work to ensure that it will not be lost.”

      “I paid State Farm to insure my boat.”

    • behavior, color Use this spelling rather than behaviour or colour for an international audience. This spelling variant also applies to many other words ending with -our.

    • capital, capitol The only time you use capitol—with an o—is when referring to the building where a government body meets. Use capital—with an a—when referring to the city where that capitol building is located or to money, capitalization of letters, and the quality of something being great.

      “The senator worked on Capitol Hill.”

      “Salem is the capital of Oregon.”

      “I say, that’s a capital idea!”

    • e.g., i.e., et al., etc Instead use for example (e.g.), in other words (i.e.), and others (et al.), and and so on (etc.) whenever possible. However if you must use the Latin abbreviations, do not italicize them, and punctuate them consistently with how you would have punctuated the phrases that they replace.

    • email Common noun. Never refer to this as electronic mail. Spell it as a single word with no hyphen. Unless specifically directed to do otherwise, email addresses are generally typed using all lowercase letters.

    • farther, further Use farther for physical distance, and use further for additional, or an abstract distance:

      “I drove farther than she did.”

      “For further discussion, see me later.”

    • fewer, less Use fewer in relation to a quantity of countable discrete nouns, and less for non-discrete, uncountable nouns.

      “The process required less time.”

      “The process required fewer hours.”

    • gray, grey Use gray rather than grey for an international audience.

    • globalization Use this spelling rather than globalisation for an international audience. This also applies to many other words ending with -sation when the s is soft.

    • hanged, hung People are hanged, objects are hung.

    • internet Common noun: do not capitalize.

    • its, it’s Only use the apostrophe on its to denote a contraction of “it is.” Its without an apostrophe shows a possessive.

      “Its high price implied that it’s valuable.”

    • lay, laid, laying Lay is a present tense verb used when the subject is acting on the object. Laid is the past tense as well as the past participle of lay:

      (Present) “I lay the book down.”

      (Past) “I laid that down yesterday.”

      (Past participle) “She must have laid the book down.”

    • lie, lain, lying Lie is the present tense verb meaning the subject is doing the action. The past tense of this word is lay, and the past participle of this word is lain.

      (Present) “I lie down to sleep.”

      (Past) “Yesterday I lay on the couch all day.”

      (Past participle) “He would have lain in bed all day.”

    • multicore Common noun. Spell it as a single word with no hyphen.

    • nevertheless This means despite or notwithstanding and is always spelled as a single word.

    • straightforward This means clear or unambiguous and is spelled as a single word.

    • their, they’re, there Use their as the possessive form of they. Use they’re as the compound form of they are. Use there to indicate a direction or place.

      “They’re using their new tools over there.”

    • toward, towards Both are acceptable, however favor toward for American and global audiences.

    • trade show Common noun. Spell as two words.

    • versus, vs Except for very formal writing, use the abbreviation, always with a period after the second letter.

      “Philip Glass vs. John Cage.”

    • via The word “via” is ostentatious if it means nothing more than “by” or “with.” Use the simpler word instead.

    • web, website, web page Common nouns. Website should be spelled as a single word, however continue to split web page into two words. Also, refer to “the web,” not to “the worldwide web.”

    • white paper Spell as two words.

    • worldwide Spell as a single word.

    • your, you’re Use your as the possessive form of the word you. Use you’re as the contraction of you are.

      “I believe you’re using your bicycle incorrectly.”

    [ Back to the category list ]

    Abbreviations

    We use “abbreviation” to mean acronyms, which are pronounceable, initialisms, which are not, and any other kind of shortened form. Also see Acronyms in the General layout and style section for more information.

    Respect the spelling and casing of third party acronyms, names, and terminology. Investigate who invented a thing and named it. For examples, it’s JavaScript, Wi-Fi, LaTeX, and JPEG, not Javascript, wifi, Latex, or jpeg.

    • Acronym list For documents with a large number of acronyms, include an acronym list either at the front of your document or as an appendix. In this list, only capitalize proper nouns or acronyms that require capitalization.

    • Articles Choose the the indefinite article (a, an) for the acronym based on how it is typically pronounced. For example, the term “URL” is more often pronounced as the letters “you are ell” instead of as a word “earl,” so the preferred indefinite article is “a” as in “a URL.”

    • Casing in acronyms

      • Proper name of a company, organization, or person Use the same capitalization used by the company, organization, or person in their official literature.

        IEEE: Institute of Electrical and Electronics Engineers

      • Registered trademark Use the same capitalization as officially registered.

        PoE: Power over Ethernet

      • Product, service, or standard provided by a particular producer Use the capitalization preferred by the producer in their official literature.

        NDEF: NFC Data Exchange Format

      • Product or service provided by multiple producers Use sentence case.

        GUI: graphical user interface

        RFID: radio-frequency identification

    • Common words Don’t unnecessarily abbreviate words, such as info, 1st, Nov., and spec. Use your words: information, first, November, and specification.

    • Place names Abbreviations for provinces, states, and other administrative divisions are only appropriate in postal addresses. In other contexts, spell out the place names.

    [ Back to the category list ]

    Math and numbers

    • Equations Your word processor’s equation editor will typically produce a higher quality result than other solutions; it’s worth giving it a try.

    • Exponents Mathematical exponentiation is often represented either by superscript (2³²) or with the caret symbol (2^32). In text exponents should always be written in superscript form (2³²). In code then the natural notation for the programming language should be used.

    • Numerals When used in a sentence, either spell out all numbers, or spell out numbers from zero to ten and use numerals for numbers 11 and higher. An exception is to spell out large round numbers, such as one hundred. When not in narrative prose, such as in a list or in a technical document, use numerals with abbreviated units of measurement, separated by a space, as shown in Space below.

    • Ranges There are several ways to indicate a range: an en dash (2–10), words (2 to 10 or 2 through 10), two or three dots (2..10), or brackets with a comma [2,10]. Any of these notations will work if used consistently in a document.

    Is (2..10) the same as [2…10]? In math it is not, since one is the open interval, while the other is the closed one. But that is beyond the scope of this style guide.

    • Space A space goes between the number and the unit of measure. When listing a temperature there is no space between the number and the degree symbol (°)., but there is a space between the degree symbol and the unit

      1.0 mV, 120 mm, 110° C.

    • Special characters The prefix for “micro” (one millionth) is a Greek mu (μ), not a Latin u.

    [ Back to the category list ]

    Document design for PDF

    Many documents these days are read on a screen either as PDFs or as web content, rather than in print. This section discusses formatting content specifically for output to a PDF for reading on-screen.

    • Cover Set the title in large, bold text, and if possible, set the footer to omit the page number on this page.

    • Page numbering The practice of using lowercase roman numerals for document front matter such as a table of contents is not appropriate for today’s on-screen documents. Begin the page numbering with page 1 for the cover page, so that the nth page of the PDF file should be reflected as the nth page in the page number shown on the page.

    • Even and odd pages Today, as many documents are no longer printed and bound, we no longer need to use different page layouts for odd- (recto/right) and even-numbered (verso/left) pages. The running heads and page numbers may remain aligned on the right or left side of the page or centered, but do not move them back and forth.

    • Page breaks In short documents, unless a new section would otherwise start very low on a page, do not force new sections to begin on a new page. For longer documents, only force a new page for your highest level of heading, such as for a new chapter or main section. In those cases, it does not matter if that is an odd- or even-numbered page. Unless the document is intended specifically for printing and binding, do not insert a blank page to force a section to begin on an odd-numbered page.

    • Hyperlinks Navigability is important for documents that will be read on a computer. Design your table of contents and index such that the page numbers or text are hyperlinked to take the reader to the appropriate page. When you insert a cross reference in your document, make it a link that will take the reader to the referenced materials. Format this content to make it obvious to the reader that it is a link. (See Hyperlinks in the General layout and style section for more information.)

    [ Back to the category list ]

    * Public Relations Writing: Form & Style. Doug Newsom, Bob Carrell. Wadsworth Publishing Company. 1995. [Return to the Punctuation section] The icons on this page used under license are from The Noun Project.