This style guide is for authors, copyeditors, and proofreaders working on books of all formats. As writers and editors, we know that language changes over time, so please check back regularly for updates to terms and conventions. Recent additions will be set in bold for a few months.
Authors, please also consult the authoring documentation for the format in which you’re writing (Asciidoc, HTMLbook, DocBook, or Word). For sponsored projects, please see our statement of editorial independence.
For term conventions, check our guide and word list first, then The Chicago Manual of Style, 17th edition, then Merriam-Webster’s Collegiate Dictionary. Use your book-specific word list (provided by production) to document style choices that differ or are not covered here (e.g., A.M. or a.m., data center or datacenter).
To avoid unintentional bias, when writing about groups of people, check the group’s advocacy organization for guidance on appropriate language. O’Reilly aims to avoid the following problematic language and recommends using resources such as the Conscious Style Guide, the University of Washington’s “IT Inclusive Language Guide”, and the Disability Language Style Guide for alternatives.
Avoid language that is unnecessarily gendered (e.g., middleman, man hours), violent (e.g., hit, kill), and otherwise exclusionary, incendiary, or imprecise (e.g., crazy, dummy, master/slave, tribe). Avoid associating positive or negative characteristics with colors that are also associated, problematically, with people (blackbox, black hat, white list, etc.). Always follow a person’s preference and note exceptions, if necessary (e.g., quoting research that is decades old or technology that has fallen behind the times).
For questions specific to your book or assignment, please consult with your editor or production editor.
Because we use a single set of source files to produce the print and electronic versions of our books, it’s important to keep all formats in mind while writing and editing:
Avoid using "above" and "below" to reference figures, tables, examples, unnumbered code blocks, equations, etc. (e.g., "In the example below…"). Using live cross references (e.g., "see Figure 2-1") is best, but when that’s not possible, use "preceding" or "following," as the physical placement of elements could be different in reflowable formats.
Anchor URLs to text nodes whenever possible, like you would on a website. See Links for more information.
Avoid anchoring URLs to generic words or phrases such as "here," "this website," etc. Be as descriptive as possible because the print version of your book renders hyperlinks like this: "text anchor (http://url.example.com/)."
For example, this:
Download the source code (http://www.url.thisismadeup.com) and install the package"
is more useful than this:
"Download the source code from this website (http://www.url.thisismadeup.com) and install the package."
Long URLs will be shortened so that they’re easy for print readers to type manually.
Do not link to products on any sales channels other than oreilly.com, including Apple, Google, or Amazon. Apple and Google will refuse to sell content that links to products on Amazon. Vendors, please flag any links to these sales channels and let the production editor know they exist.
Saying "XX book is available on Amazon"—sans link—is OK.
For information about formatting code in books written in Word or Google Docs properly for conversion, see Formatting Code in Word.
For any words or conventions not covered here, refer to The Chicago Manual of Style, 17th edition and Merriam-Webster.
See the The Chicago Manual of Style, 18th edition for questions about abbreviations and acronyms that are not covered here:
A.M. and P.M. or a.m. and p.m.—be consistent.
Acronyms should be capitalized when expanded only if the term is a proper noun (and spelled that way by the company). For example, key performance indicator (KPI), but Amazon Web Services (AWS).
In units of measure, do not use a hyphen. For example, it’s 32 MB hard drive, not 32-MB hard drive. (Though when the unit is spelled out, use a hyphen, e.g., 32-megabyte hard drive.)
K = 1,024; k = 1,000. So a 56 kbps modem is equal to 56,000 bps, while 64 K of memory is equal to 65,536.
Many acronyms are common enough that they should be used without expanding. For our books, that typically includes (but is not limited to) AI when it stands for artificial intelligence, API (application programming interface), CLI (command-line interface), CPU (central processing unit), HTML (HyperText Markup Language), IP (Internet Protocol), UI (user interface), UX (user experience), etc.
United States and United Kingdom should be spelled out on first mention. After that, just use the acronym with no periods (so, US or UK).
University degrees (e.g., B.A., B.S., M.A., M.S., Ph.D., etc.) can appear with or without periods—just be consistent.
When citing materials in bibliographies, reference lists, or footnotes, use the “Notes and Bibliography” system from the The Chicago Manual of Style, 18th edition. Chicago also has an Author-Date system that some authors prefer, which is perfectly acceptable. If there is no discernible consistency, suggest Chicago's Notes for footnotes and Bibliography for endnotes or back matter.
Let your production editor know which of Chicago's systems you applied by adding a note to the Word List Doc.
In general, when referring to another book within a book’s text, include the author name(s) for up to two authors. For three or more authors, state the first author name, followed by “et al.” (be sure to include the period). On first reference, include author and publisher name. For example, "You can find more information in The Elements of Typographic Style by Robert Bringhurst (H&M)," or "For more information, consult Robert Bringhurst’s The Elements of Typographic Style (H&M)." On subsequent references, just use the book title.
When referencing an O’Reilly book within the text, note only "O’Reilly" in parentheses, not "O’Reilly Media, Inc." References to other O’Reilly books should be linked to the book’s catalog page.
Make sure that the catalog page is anchored to the book’s title, rather than standing on its own like this: "See Programming F# 3.0," and remember not to link to product pages where the book is available for purchase (see Considering Electronic Formats).
Footnotes should contain more than just a URL, whether a full citation for the text the URL points to or context for where the link leads. For example:
Not this:
Maximum line length for code varies slightly between book formats. Consult the table below to find the maximum line length for your book’s series within Atlas v2. If writing in Word, please keep code within the margins that appear in the Word template and indicate proper linebreaks and indents for all code. Indent using spaces, not tabs.
| Series | Body (top-level code) | Examples | Lists | Readeraids | Sidebars |
|---|---|---|---|---|---|
Animal (7x9) |
81 |
85 |
73 |
57 |
77 |
Animal 6x9 |
64 |
68 |
56 |
40 |
60 |
Report 6x9 |
64 |
68 |
56 |
40 |
60 |
Trade 6x9 |
76 |
72 |
65 |
80 |
69 |
Cookbook |
81 |
85 |
73 |
57 |
77 |
Make 1-column |
89 |
89 |
81 |
66 |
39 |
Make 2-column |
45 |
46 |
35 |
28 |
40 |
Make Getting Started |
63 |
67 |
60 |
51 |
60 |
Nutshell |
71 |
75 |
67 |
60 |
75 |
Pocket Ref |
51 |
55 |
50 |
42 |
51 |
Theory in Practice |
81 |
85 |
77 |
51 |
83 |
We use a tool called Pygments to colorize code. In most books, code will appear in black and white in the print book and in color in all electronic formats, including the web pdf. If you’re an author, please consult the list of available lexers and apply them to your code as you write. To apply syntax highlighting in Asciidoc, consult Writing in AsciiDoc. To apply syntax highlighting in DocBook, consult the DocBook Authoring Guidelines. To apply syntax highlighting in Word, consult the O’Reilly Media Word Template Quickstart Guide.
When copyediting in Word, please do a global search and replace for tabs in code (search for \^t to find them) before submitting files for conversion; tabs will not convert. A general rule of thumb is one tab can be replaced with four spaces (which is the same number that the clean-up macro in the ORA.dot template uses). However, this number can vary, so the most important thing is that copyeditors replace tabs with the numbers of spaces needed to match the indentation and make sure levels of indentation are preserved.
Here are a few examples of cross references:
Chapter: See Chapter 27.
Section: See “Treatment” on page xx. (The text “on page xx” will be dynamic in Atlas, updating as page numbers change.)
Figure: ...as shown in Figure 1-1.
Sidebars: See “A Note for Mac Users” on page xx. (As with section xrefs, the page number will update automatically in Atlas.)
More details on cross-references in Asciidoc are available in our Writing in AsciiDoc guide.
These cross-reference styles are also available in DocBook under various <xref>: formats. Please refer to the DocBook Authoring Guidelines.
For information about styling URLs and hyperlinks, see Considering Electronic Formats.
Here is some additional guidance on what to spell out and when:
Always use the symbol % with numerals rather than the spelled out word (percent), and make sure it is closed up to number: 0.05%. Unless the percentage begins a sentence or title/caption, the number should be a numeral with the % symbol.
Centuries follow the same zero through nine rule, so those will usually be numerals (i.e., 20th century, 21st century).
In most numbers of one thousand or more, commas should be used between groups of three digits, counting from the right (32,904 NOT 32904). Exceptions: page numbers, addresses, port numbers, etc.
Spell out numbers from zero to nine and certain round multiples of those numbers unless the same object appears in a sentence with an object 10 or over (five apples; five apples and one hundred oranges; 5 apples and 110 oranges).
Spell out ordinal numbers first through ninth, use numerals for 10th and above. No superscript.
Use numerals for versions (version 5 or v5).
Use a numeral if it’s an actual value (e.g., 5% 7″ $6.00).
Whole numbers one through nine followed by hundred, thousand, million, billion, and so forth are usually spelled out (except in the sciences or with monetary amounts).
This is how we format dates and other numbers:
1980s or ’80s.
32-bit integer.
Phone numbers can appear in the format xxx-xxx-xxxx.
Use an en dash (–) with negative numbers or for minus signs, rather than a hyphen.
Use multiplication symbol “×” for dimensions, not "by" (e.g., "8.5 × 11").
Use spaces around inline operators (1 + 1 = 2. NOT 1+1=2).
Every formally numbered figure, table, and example should be preceded by a specific in-text reference (for example: see Figure 99-1; Example 1-99 shows; Table 1-1 lists, etc.). Formal figures, tables, and examples should not be introduced with colons or phrases like “in the following figure,” or “as shown in this table.” Though we do support unnumbered informal figures/tables/examples, these should be used only for elements whose contents are not discussed at length or referred back to. Lack of specific in-text references may cause incorrect placement of figures. See Cross References for more detail on including cross references.
If you are writing or copyediting in Word, figure, table, and example numbers should be numbered as follows: 1-2 (note hyphen [-], not en dash [–] between numbers). The first number is the chapter number. This will be soft-coded in production if not during the writing process.
If you are writing or copyediting in Asciidoc, please refer to Writing in AsciiDoc for examples of Asciidoc cross references.
If you are writing or copyediting in DocBook, please reference each figure, table, and example with an <xref>.
Any word groupings within a figure should have an initial cap on the first word only, with the exception of proper nouns. Generally, we don’t use periods at the end of these word groupings.
Figure 1-1. Figure captions are sentence-cased, with the exception of proper nouns. Code styling is allowed within the figure name or caption. There is no period after figure captions. Exceptions should be discussed with your production editor (e.g., if several long captions require punctuation, we can collaborate on efficient ways to achieve consistency).
Table 1-1. Column heads and table titles are sentence-cased, with the exception of proper nouns. Code styling is allowed within the table name or caption. There is no period after table titles.
Example 1-1. Example titles are sentence-cased, with the exception of proper nouns. Code styling is allowed within the example name or caption. There is no period after example titles.
When working in Word, make sure all table cells are tagged with a cell paragraph tag, even if they’re blank. Any bold “headings” that appear below the very first row of a table should be tagged CellSubheading rather than CellHeading.
Also in Word, all figures must be within a FigureHolder paragraph followed directly by a FigureTitle paragraph.
There are two main contexts where generative AI content appears: chatbot/UI interactions, and code/programming interactions. The former will appear in more non-technical books, while the latter is common in books aimed at developers and engineers. Query production if you're not sure what category something belongs in.
Display "conversational" text generated in an AI chatbot environment in blockquotes. To separate a prompt from a response, showing who “said” what, use italics:
Prompt: Can you write some text?
(insert appropriate technology name here): Sure can!
We want to accurately replicate the back-and-forth between human and AI. Human prompts can be edited very lightly (e.g., punctuation, capitalization), but AI-generated text should be kept verbatim. If AI output is edited for some reason, be sure to still acknowledge the AI's contribution. It must be clear what is AI-generated.
Display content that has a programming context in a code block, with a normal paragraph separating the prompt and the response as needed. The code content should be left verbatim, for the most part, though typos can be flagged for author/production attention. There will not be syntax highlighting. Here is an example:
prompt = "Write an email apologizing to Sarah for the tragic gardening mishap. Explain how it happened." output = generator(prompt) print(output[0]['generated_text'])This generates the text:
Solution 1: Subject: My Sincere Apologies for the Gardening Mishap Dear Sarah, I hope this message finds you well. I am writing to express my deep...
Headings should not contain inline code font or style formatting such as bold, italic, or code font.
Headings should always immediately precede body text. Do not follow a heading with an admonition or another heading without some form of introductory or descriptive text.
Follow these rules for capitalization in headings:
A- and B-level headings are initial-capped (or title case)in most of our design templates. Capitalize the first letter of each word, with the exception of articles, conjunctions, and program names or technical words that are always lowercase.
C-level headings have initial cap on the first word only (also called sentence-case), with the exception of proper nouns and the first word that follows a colon (unless that word refers to code and should be lowercase).
D-level headings (rare) are run-in with the following paragraph and have an initial cap on the first word only, with the exception of proper nouns and the first word that follows a colon (unless that word refers to code and should be lowercase), with a period at the end of the heading.
Sidebar titles are initial-capped, or title case (like A- and B-level headings, mentioned previously).
Admonition (note/tip/warning) titles are initial-capped, or title case (like A- and B-level headings, mentioned previously). Admonition titles are optional.
Hyphenated words should both be capped if the second word is a main word, but only the first should be capped if the second word isn’t too important (it’s a bit of a judgment call). For example: Big-Endian, Built-in. See The Chicago Manual of Style.
Prepositions of four letters or fewer are not initial-capped, unless they function as part of a verb (e.g., “Set Up Your Operating System”).
Subordinating conjunctions (e.g., as, if, that, because, etc.) are always initial-capped (even if they are four letters or less).
In books produced in Atlas, URLs should be anchored to descriptive text where possible. In ebook versions, the markup will render like this:
Navigate to the O'Reilly home page for more information.
In the print book, the URL will unfurl in a parenthetical after the linked text:
Navigate to the O'Reilly home page (https://oreilly.com) for more information.
Because of this difference in appearance of links in ebooks and print books, long and complex URLs are shortened during production. In the past, we used bit.ly to shorten these URLs, but as of May 2019, all shortened links will be hosted and tracked internally, using the oreil.ly short link.
We do not anchor URLs to text in books produced in InDesign.
Typically, we use three types of lists: numbered lists, for ordered steps or chronological items; variable lists, for terms and explanations/definitions; and bulleted lists, for series of items. List items are sentence-capped. List items should be treated as separate items and should not be strung together with punctuation or conjunctions. Unless one item in a list forms a complete sentence, the list's items do not take periods. If one does form a complete sentence, use periods for all items within that list, even fragments.
NOT O'Reilly style:
O'Reilly style:
Following are examples of each type of list.
The following series of items is an example of a bulleted list:
Labels
Buttons
Text boxes
“Bulleted” lists nested inside of bulleted lists should have em dashes as bullets.
Frequently, bulleted lists should be converted to variable lists. Any bulleted list whose entries consist of a short term and its definition should be converted. For example, the following bulleted list entries:
Spellchecking: process of correcting spelling
Pagebreaking—process of breaking pages
should be variable list entries:
Process of correcting spelling
Process of breaking pages
The following list of step-by-step instructions is an example of a numbered list:
Save Example 2-1 as the file hello.cs.
Open a command window.
From the command line, enter csc /debug hello.cs.
To run the program, enter Hello.
The following list of defined terms is an example of a variable list:
This creates a setup file that automatically installs your files and resources.
This helps deploy a web-based project.
For anything not covered in this list, please consult the Chicago Manual of Style, 18th edition.
Commas and periods go inside quotation marks.
Curly quotes and apostrophes (“ ” not " ") in regular text.
Ellipses are always closed (no space around them).
Em dashes are always closed (no space around them).
Footnote markers in running text should always appear after punctuation (e.g., ".1" and not "1.").
Footnotes in running text are numbered and start over at 1 in each chapter. (More details about styling footnotes in AsciiDoc are in Writing in AsciiDoc.)
For menu items that end with an ellipsis (e.g., "New Folder…"), do not include ellipsis in running text.
Lowercase the first letter after a colon: this is how we do it. (Exception: headings.)
No period after list items unless one item forms a complete sentence (then use periods for all items within that list, even fragments).
Parentheses are always roman, even when the contents are italic. For parentheses within parentheses, use square brackets (here’s the first parenthetical [and here’s the second]).
Serial comma (this, that, and the other).
Straight quotes (" " not “ ”) in constant-width text and all code. Some Unix commands use backticks (`), which must be preserved.
Table footnotes are lettered (a, b, c, etc.) and appear directly after the table. They should be kept to a minimum.
The following shows the basic font conventions used in O’Reilly books. Follow these links for detailed instructions for applying these styles in Asciidoc, DocBook, and Word.
If you want to use a font convention that is slightly different for one of the following items, check with your editor first—some things can change; some can’t. For example, URLs will not be anything but italic, but you might come up with a different font convention for function names or menu items. If you have a “new” element, please consult with your editor about which font to use.
| Type of element | Final result |
|---|---|
Filenames, file extensions (such as .jpeg), directory paths, and libraries. Exception: Python packages (e.g., NumPy, scikit-learn, TensorFlow, etc.) are roman and cased according to convention. |
Body font italic |
URLs, URIs, email addresses, domain names |
Body font italic |
Emphasized words (shouting!). Please use italics rather than bold for emphasis. |
Body font italic |
First instance of a technical term |
Body font italic |
Code blocks |
|
Registry keys |
|
Language and script elements: class names, types, namespaces, attributes, methods, variables, keywords, functions, modules, commands, properties, parameters, values, objects, events, XML and HTML tags, and similar elements. Some examples include: |
|
SQL commands ( |
|
Replaceable items (placeholder items in syntax); “username” in the following example is a placeholder:
|
|
Commands or text to be typed by the user |
|
Line annotations |
Body font italic (but smaller) |
Placeholders in paths, directories, URLs, or other text that would be italic anyway |
|
Keyboard accelerators (Ctrl, Shift, etc.), menu titles, menu options, menu buttons |
Body text |
These font conventions may vary slightly for each project; please consult your editor, the production editor, or the freelance coordinator if you have any questions. Please note: Word authors should refer to the Word Template Quickstart Guide; DocBook authors should refer to our DocBook Authoring Guidelines (username: guest; leave the password blank).
It’s very important to follow tagging conventions for terms. The method for applying conventions will vary depending on the format: Word/OpenOffice, DocBook XML, or InDesign. Please consult with your editor or toolsreq@oreilly.com for instructions specific to each environment.
For Word copyediting, please do the following before submitting files for conversion: replace any tabs in code with the appropriate number of spaces (see earlier section, Code); convert any remaining Word comments to tagged Comment paragraphs highlighted in blue; search for any manual linebreaks (^l) and delete or replace with paragraph breaks as appropriate; and accept all changes and make sure filenames adhere to house style.
Avoid obscenities and slurs, and obscure if included (grawlix, a two-em dash, etc.)
Avoid using the possessive case for singular nouns ending in “s,” if possible. So, it’s “the Windows Start menu,” not “Windows’s Start menu.”
Avoid wholesale changes to the author’s voice—for example, changing the first-person plural (the royal “we”) to the first-person singular or the second person. However, do try to maintain a consistency within sentences or paragraphs, where appropriate.
Close up words with the following prefixes (unless part of a proper noun) “micro,” “meta,” “multi,” “pseudo,” “re,” “non,” “sub,” and "co" (e.g., “multiusers,” “pseudoattribute,” “nonprogrammer,” “subprocess,” "coauthor"). Exceptions are noted in the word list (e.g., "re-create," "re-identification").
Common foreign terms (such as “en masse”) are roman.
Companies are always singular. So, for example, “Apple emphasizes the value of aesthetics in its product line. Consequently, it dominates the digital-music market” is correct. “Apple emphasize the value of aesthetics in their product line. They dominate the digital-music market” is not. (Also applies to generic terms “organization,” “team,” “group,” etc.)
Do not stack admonitions, sidebars, or headings.
Do not use a hyphen between an adverb and the word it modifies. So, “incredibly wide table” rather than “incredibly-wide table.”
Introduce unnumbered code blocks with colons.
Use “between” for two items, “among” for three or more. Use “each other” for two, “one another” for three or more.
Use the American spellings of words when they differ.
We advise using a conversational, user-friendly tone that assumes the reader is intelligent but doesn’t have this particular knowledge yet—like an experienced colleague onboarding a new hire. First-person pronouns, contractions, and active verbs are all encouraged. (Copyeditors: please check with your production editor if you wish to suggest global changes to tone.)
When referring to software elements or labels, always capitalize words that are capitalized on screen. Put quotes around any multiword element names that are lowercase or mixed case on screen and would thus be hard to distinguish from the rest of the text (e.g., Click “Don’t select object until rendered” only if necessary.)
Use Chicago Manual of Style, 18th edition for anything not mentioned here.
Bulleted lists on the back cover should begin with a capitalized word and end with no punctuation. Even if the list item is a complete sentence, it will not take a period.
Lowercase job attributions in cover copy as much as possible. Formal job titles can be title case, and anything more informal should be lowercase (most will fall in the second category). It is OK to mix casing if there are multiple attributions with differing levels of formality. If the attribution starts on a line of its own, it will be sentence-cased. For example:
"This is a great book."
—Robin Linacre, lead author of Splink
"I read this every day."
—Sawyer Nyquist, Chief Engineering Officer, The Data Shop
This section lists favored spelling variations and default conventions for common terms, acronyms, and abbreviations. Use Merriam Webster’s Collegiate Dictionary for anything not covered here.
A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z |nginx (server)