Holloway Editorial Style Guide

Style rules and guidelines for anyone who writes, edits, or contributes material published on Holloway.
40 pages (2 hours read time) and 33 links — last update 2 months ago

edition

Credits

Introduction

This Guide is for anyone who writes, edits, or otherwise contributes to a Holloway Guide. It is intended to ensure consistency, accuracy, and brand voice of all Holloway Guides and related content.

About Holloway2 links

Mission

To assemble and publish reliable knowledge from experts for all to learn from and build on. You can read more here.

Audience

We write for an audience that is 100% intelligent and also 100% naive about the topic at hand.

Editorial principles

Our editorial principles are:

  1. To offer helpful guidance
  2. …with long-term value
  3. …that is trustworthy
  4. …and accessible.

Voice and Tone9 minutes, 4 links

Our aspiration in writing Guides is that they be both deep and engaging. Technical and accessible. We want to earn respect from both experts and beginners. The voice and tone we use are critical to striking this balance.

Voice

At Holloway, we’ve paced the halls of many a company large and small in our readers’ shoes—we know that modern work is fraught with endless choices and the tool of record for navigating those choices (searching Google) yields questionable results at best. The Holloway voice is that of a trusted friend sitting across from our reader over coffee. The trusted friend of our reader has years of experience, but is not an “expert” removed from our reader by multiple degrees and decades of experience. While the trusted friend harnesses the knowledge of experts, they are perhaps only two or three years ahead of the reader. They can remember what it is that motivates the reader and what scares them; they understand the anxieties with which the reader approaches a topic or problem; they get that a reader might be urgently trying to figure out some course of action, but they also know the reader would love to delve into all the nuances of a topic, given the time.

Our voice wants to converse, not just drop information into the vessel of a reader. That’s not what you do to friends! But our friends really, really want to move from a 2 or 3 on Tim Urban’s Scale for understanding complex ideas to a 7 or 8—someone who doesn’t just reiterate popular opinion but can answer expert questions and reconcile contradictory thoughts about the idea. Because that’s how they can have better conversations. And they know we can help them with that. With a conversational, trustworthy voice and a fervor for research, we prefer clarity over flowery descriptions, and accuracy over easy answers. We use humor where it can help make our readers feel comfortable with a difficult topic; humor can help people feel like a topic is approachable, like the writing is for them, and like they are part of the conversation.

Here it is broken down: 1. We prioritize rigor. Our writing is accurate, precise, logical, and clear. Readers come to us often after failing to find trustworthy, comprehensive coverage of something complex. Save the fluff for sandwiches. 2. We are direct and genuine. We always respect the reader’s intelligence. The ability to learn has little to do with how much exposure someone has had to a particular topic in the past. Without oversimplifying details or writing for short attention spans, we aim to intrigue visitors by giving them a clear sense of what we’re going to offer, so that they know if they stick around and keep reading, they’re going to learn something of value. 3. We embrace complexity and don’t avoid conflicts. It’s our job to present the real complexities inherent in our topics. It’s tempting to hide messy or confusing details from readers, but we must not underestimate people’s ability to manage information when it is supplied well. When there is controversy, we give an overview of perspectives, reference the key people or resources on different sides, and give rationale and context. We do offer advice when we strongly believe that readers might be supplied with advice that is bad for them elsewhere. 4. We are empathetic. We never tell readers they should already know something, or assume that they come from a particular place, are of a particular age, or have a particular background or level of experience. In fact, we never use the phrase “you should.” We speak to people’s anxieties. We are never thoughtless when using humor, which we do sparingly. Poorly or thoughtlessly executed, “jokes” can alienate, anger, and even do harm. When calling out bad behavior, we always punch up, not down.

Tone

Principles of voice will remain true across Guides, articles, social media, and blog posts, while the tone might change depending on the medium and/or audience—whether we’re writing or editing for a Guide, a blog post, an email to customers, or social media. The emotional and mental states of people engaging with these different platforms can vary; while the voice of friendly rigor is the same across all Holloway output, casual humor and slang make more sense on Twitter than they do in a Guide, and personal opinions make a lot more sense in a newsletter than they do in a blog post. We always use first-person plural in all our publications and across social media, with the exception of newsletters, which are written by individuals.

Style

In general, we adhere to the Chicago Manual of Style. Here’s a few key high-level points to consider across all aspects of our content.

  • We create Guides, not books. Avoid any wording along these lines, including:

    • Book. We prefer Guide (always capitalized) wherever possible.
    • Chapter. Use section instead.
    • Edition. This may vary based on context, but likely either version or revision would apply here.
  • Use active voice. Grammar Girl sums it up best.
  • Confront jargon. We’re not saying don’t use it, but call it out, and explain it’s purpose and put it in context.
  • Be positive and helpful. Except when you clearly shouldn’t. Calling out harmful, negative, pitfall-ridden territory sometimes requires speaking less softly.

Punctuation9 minutes

There are a few helpful reminders that should be checked thoroughly for consistency:

Commas

An important thing to know about the common comma that can save you loads of agonizing: It isn’t used to connect, it’s used to separate. If you’re trying to connect two separate thoughts, you mean to use a semicolon, an em dash, or a colon. This is a useful way to tell if you’re comma splicing, or using a comma to separate two pieces that can stand on their own (otherwise known as independent clauses). Use commas when:

  1. Separating coordinate adjectives, aka, adjectives that cannot be separated by the word and,as in: “What a beautiful, thoughtful piece of writing.” “Yes, it is thoughtful and beautiful, how wise.”

    • If your adjectives cannot be separated by and, there’s no comma, as in, “The gross arrogance of this editor is unbelievable.”
  2. Separating the final item in a list. Yep, Holloway uses the Oxford comma! That means that when making a list, put a comma between and and the final item, as in: “Bird, bees, and overwhelming loneliness”

Colons

Use them when:

  • Introducing a list of bullet points or steps (always)
  • Extrapolating on a point you just made (sometimes)
  • Introducing a question (sometimes)

Semicolons

Use them when:

  • Separating the items in a list of three or more

Hyphens and en dashes

There are three types of dashes, the hyphen, the en dash, and the em dash. Most people are familiar with hyphens, but they are often overused. En dashes are mostly structural, and em dashes often present significant challenges. Here’s how we use them:

  • Hyphen (-) This single, small dash is used to combine words—two or more—that make up a compound adjective, like “well-respected” or “holier-than-thou.” Hyphens do not have spaces around them. Hyphens are also used to combine a prefix with a pronoun, as in “un-American,” but not in regular nouns like “untenable.” You do not need to use a hyphen when the compound adjective you’re looking at ends in –ly, as in “a fascinatingly written article,” nor when the compound adjective follows the noun, as in “the article was well written.” However, “a well-written article” is correct, because the compound adjective precedes the noun. Some compound adjectives, like when they contain more than one verb, will always have a hyphen: “the dish was carry-out” and “a carry-out dish” are both correct.
  • En dash (–) For our purposes, en dashes are used for two things: 1) to combine numerals. In this context (“10–20”), the en dash means “through” or “to” 2) to combine subjects that have equal weight, as in, “He is a British–American author.”

Tip: If you use a Mac, the en dash can be typed as ⌥-

Em dashes, parentheticals, and clauses

Em dash (—) The em dash is a favorite punctuation at Holloway, because it’s primarily emotional. In most cases, an em dash can be replaced by a comma clause or a set of parentheses and technically the sentence will be correct. But each of these options represents a different emotional register. While a comma clause indicates a piece of information that can be considered equal to the rest of the information in a sentence, and a parenthetical usually contains supplemental, surprising, clarifying, or detracting information, the em dash is used to separate—that’s right—the information in a sentence that you definitely want the reader to notice. They are used to mark a shift in tone or to mark off important information you don’t want anyone to miss. They’re also better to use than a comma in the case that your sentence already has a great deal of commas. We use the em dash a lot at Holloway because it tends to bring a conversational tone to complex constructions containing a lot of information. You’ll notice em dashes throughout this text—you can refer to these if you get confused!

  • There should never be spaces around an em dash.
  • Another note on parentheses: they cannot correct the damage of a run-on sentence.

Tip: If you use a Mac, the em dash can be typed as ⇧⌥-

Note: In British written English, the en dash does the work of the em dash, which is hardly used outside the U.S. We just like things bigger here.

Brackets

Our main use of brackets is to provide or clarify information within a quote that doesn’t appear in the original quote. Say Cynthia is a really cool dancer, and is participating in a dance contest later this month. Angelica wants to tell you (on the record) something about Cynthia: “She will win.” When it turns out that the article you’re writing has more to do with Angelica and in fact you aren’t even mentioning Cynthia’s dance ability, but still want to include Angelica’s line about her, because it just says so much about who Angelica really is, you might do this: “She will win [the dance competition].” Got it?

Note: brackets are also used heavily in Markdown format, such as to format links, but the reader never sees them.

Ampersands

Use them in company names (AT&T) and names of law firms. Do not use them otherwise in text, headings, or section titles.

Typography and Font Conventions4 minutes, 2 links

Roman

This refers to normal text, like this, that is neither italicized nor boldfaced. Also known as upright text.

Italics

Italics are used for many things, including:

  • To emphasize or stress certain words or phrases. Italics used for emphasis can often change the meaning of a sentence, and mimic patterns in speech. For example, “Timmy, don’t marry her,” might mean something different than, “Timmy, don’t marry her.”
  • Book titles
  • Names of blogs
  • Newspapers, magazines, and periodicals

    • It’s The New York Times, not the New York Times; but it’s also the Pentagon Papers, not The Pentagon Papers
  • Foreign words or phrases
  • Names of ships

danger️ If a phrase is italicized, only the punctuation that the phrase contains should be italicized. If a colon or semicolon or comma separates the italicized phrase from further roman text, do not leave it italicized!

We also use italics in the following ways:

  • When referring to an example of a word rather than a word in context, e.g. “When someone says dilution, what they often mean is…”
  • People often put examples of words in quotation marks, but this can be confusing if a text already includes quoted material, and it also tends to look quite bulky.
  • Sometimes, however, it might be more appropriate to put a reference to a word in quotation marks, particularly when referring to the use of jargon.

Quotation marks

When quoting within a quote, use single quote marks, like, “He said, ‘I love you,’ but I could hear the air quotes.” Colons and semicolons go outside quotation marks. If the punctuation applies to the quote, put it inside; if it doesn’t, put it outside. We also use quotation marks to offset the following:

  • Titles of blog posts: When naming the title of a blog post, put quotation marks around the title—even when the title is also an external link. Like this:

    … as Founder Collective director Joseph Flaherty writes in “How to Write Better Cold Emails to VCs.”

  • Poems

  • Short stories

  • Essays

  • Articles

Boldface

Boldface is used only in definitions, because they serve a specific function in the product. We’ll explain more in the section on definitions.

Underlining

Do not use underlining. It’s a typewriter habit and not supported in Markdown or the Holloway Reader. (The Holloway Reader does use underline styling to indicate web links.)

Formatting and Style27 minutes, 14 links

Emoji (aka block styling)

Specific paragraphs (or bulleted items) can be tagged with emoji that express a special meaning. These trigger formatting rules in our product that help call out the type of content visually. The set is extensible but includes:

  • important Important and often overlooked tip
  • danger️️ Serious warning or danger (where risks or costs are significant)
  • caution A caution, limitation, disadvantage, or quirk
  • controversy Controversial topic where informed opinion varies significantly
  • confusion Common confusion or misunderstanding, such as confusing terminology
  • technical Technical point (arcane or academic and not essential)
  • new New or recent developments
  • ···

These emoji appear at the beginning of a block (“chunk,” usually a paragraph, but sometimes at the top of a bulleted list) of text, never within it. Put a space between the emoji and the first word of the chunk.

Inline emoji

Paid and login emoji, as well as media type emoji, do appear in-line, preceding linked text. They should be placed after the first parenthesis containing linked text, with no space between emoji and linked text.

  • paid paid: May require payment to read
  • login login: May require an account to read
  • Media types
  • slides slides: Slide deck or infographic
  • video video: Video
  • book book : Book or e-book
  • audio audio: Audio or podcast
  • document document: PDF or form or download
  • tool tool: Interactive online tool

Headings

Main headings

Headings come at different levels: part, section (formerly know as chapter), sub-section, and so on. We refer to these as H1, H2, and H3. These correspond to HTML levels (that is, the actual codes used on websites) as well as Markdown levels (one, two, or more # signs).

  • H1 = # = part
  • H2 = ## = main sections
  • H3 = ### = sub-sections
  • H4 = #### = sub-sub-sections

Heading guidelines

  • In H1 and H2 level, capitalize each word (excluding articles and conjunctions)
  • At H3 or deeper, do not capitalize after the first word in section headings
  • We do not want heading levels deeper than H4.
  • For headings and titles, spell out “and” rather than use an ampersand.
  • Do not use boldface in headings.
  • Italics may be used in headings rarely, such as for titles or foreign words.
  • Make your headings descriptive and informative (not “Other Ideas”)
  • Do not have repeated headings across sections (not “Further Reading” in multiple headings)

Inline headings

These are headings which are at the head of a paragraph (not H2 or H3). We often use them to guide the eye where a main heading is excessive, or to label each paragraph in a bulleted list of items.

Boldface inline headings. Avoid inline headings that are plain roman.

  • Do not boldface the colon, but do maintain other formatting (like italics) with all other punctuation (like exclamation points or quotation marks).
  • We prefer to use inline headings on paragraphs or most (or all) items in a bulleted list, but not only one or two items in a bulleted list.

Boldface and italics

Italics should be used when referencing book titles; the names of blogs; article titles; newspapers, magazines, and periodicals.

We do not italicize blog post titles.

We also use italics specific to Holloway in the following ways:

  • When referring to an example of a word rather than a word in context, e.g. “When someone says dilution, what they often mean is…”
  • People often put examples of words in quotation marks, but this can be confusing if a text already includes quoted material, and it also tends to look quite bulky.

Use boldface when you really want to offset something important or surprising. It can actually be helpful to do this as you write, because it can alert us to product features and graphic design opportunities we might employ.

  • Boldface has specific rules in Definitions.
  • Key statements: It’s also fine to boldface key statements and phrases that guide the eye.

Quoting people

Inline quotes

We follow AP style for quoting people in the context of a sentence or paragraph.

Block quotes

When you want to highlight a quote to stand out, often at the start of a section or paragraph, use the 🅀 emoji. Be sure to leave a space after the quote, followed by an em-dash and the person’s name:

Famous remarks are very seldom quoted correctly.Simeon Strunsky*

The internet is full of unattributed, un-cited quotes. Don’t add to the noise. We aim for every quote that we include to inspire but also inform. Cite your source, using a footnote whenever possible.

Lists

Lists are extremely important to the flow and readability of Guides. We use two types of lists, bullet and numbered.

Numbered lists

Use numbered lists only when laying out steps that should be taken in order.

Bullet points

We sometimes use paragraphs and sometimes bullets. Validate there is a reasonable balance, using bullets judiciously. Key pieces of content that fit together in a narrative way are good as paragraphs.

Bullets and sub-bullets encouraged whenever there is a laundry list of items, or three or more items fit together in a natural way, or the list may expand in the future via contributions. But not over-done or many levels deep.

If the paragraph before the list ends in a colon and the list is an itemization:

  • start each point with a lowercase letter
  • don’t punctuate the end of the line
  • but finish the last piece in the list with a full stop.

If there is no preceding semicolon, the bullets should each represent a different, separable piece of relevant information that can stand apart from others in the list and still be understood. It may happen that a colon precedes a list of items that are separable and stand-alone.

  • If your bullet points stand alone, use a capital letter to start each one, and a full stop to end each one.
  • If every item of a bulleted list has a small inline heading (with a colon), boldface all of them, e.g.:

    • First item: This is the first example.
    • Second item: This is the second one.
    • Third item: This is the third.

Exception: No need to bold lists of subjects under examination, eg. “Hire 1:; Hire 2:”, even if each example is followed by a colon, and especially if the explanatory text contains bolded text like numbers.

There are two types of inline links, internal (within a post or Guide, or to another Holloway resource) and external (elsewhere on the web).

Common rules

Some formatting is the same for both internal and external links:

  • Prefer the most descriptive and logical set of words as anchor text that give a clue to the linked page or linked internal section.

  • Given that, prefer shorter anchor text. Long, highlighted links (with mouseovers), especially more than five words or so, tend to be distracting and ugly.

    • Example of long article text link that could be changed to be shorter:

  • Best practices for anchor text are also guided by how SEO works.

  • Do not include parentheses or quotation marks in the linked text.

  • Do not include articles like “a” or “the” in the linked text.

  • “The Security and Exchange Commission (SEC) regulates accredited investors, a term which refers to individuals who meet certain net worth or income standards. Before accepting money…”

Use actionable words or phrases in a sentence if the action or assertion is the primary point. Prefer the verb or verb phrase over the object alone:

Nouns can work too, optionally including the adjectives or other parts of the phrase, depending on length and clarity:

  • Best: “According to a 2014 New York Times article…”
  • Still good: “According to a 2014 New York Times article…”

    • The second choice may be preferred if nearby text has additional links, and linking a longer phrase would look clunky.

In particular, avoid linking in a way that leads the reader to think you’re linking a specific noun:

Avoid using completely generic, self-descriptive anchor text that tells the reader to “read this” or “click here.”

Cross referencing (linking to material that appears in another place within the Guide) is important to the internal discoverability of our content. We call these internal links or “anchor links” (not to be confused with “anchor text”), and they help direct readers to further information on a component of a topic that might be mentioned elsewhere in a Guide.

Linking to internal text is different from linking to external text. If there is a section called “Hello There!” we link to it in markdown [like this](#hello-there). Make sure to follow each of these directions:

  • Lowercase the text.
  • Remove everything that is not a letter, number, space, or hyphen (see here for how Unicode is handled).
  • Change spaces to hyphens.
  • If a section title is not unique (this is very rare!), add “-1”, “-2”, “-3”, etc. to the link to make it unique.
  • Gesturing to topics covered next, like a roadmap.
  • Mentioning things that are technically related but were not appropriate to cover. For example, a parenthetical note mentioning how something relates to a topic covered in depth later.

When working in Google Docs, to reference another section within the Guide, simply put a section symbol (§) before the text you want to link. When the document lands, we will manually add in the links using markdown internal linking conventions.

Citations

···

We read and reference a vast amount of information. Where we don’t intend to link to a source for a reader to visit and read, we can cite it instead. Citation has to main uses:

  • Fair use: To give credit to copyrighted material
  • To cite facts or statements others have made, like most classic citations

Mechanics

In general, we prefer placing an at the beginning of a link when you are simply including the link as the citation.

You can also format in the Google doc as a normal footnote, for when you want to cite something that is more than a link, such as:

  • A book, journal, or magazine article
  • Information you obtained from a direct conversation that is not published anywhere you can point to.
  • Attribution of a quote

Guidelines

The vast majority of the time, a footnote style citation will simply point to a link: https://www.holloway.com/g/venture-capital

Anything other than that will typically follow this MLA-based general format:

Author Last, First Name. Title of container Other contributors. Version/Edition (if applicable)., Publisher, date, location (if applicable), page number.

Book

  • Carnegie, Dale. How To Win Friends and Influence People. Kindle Ed., Simon & Schuster, 1998, p. 35.

Talk

  • Jepsen, Rachel. “How To Format Citations To Win Friends and Influence People” SxSW, 2019. Austin, Texas.

Quoting from an interview (conducted by Holloway)

  • Nash, Courtney. Interviewed by Pepper Nash, 2019, Bellingham.

Quoting from a source, anonymous

  • e.g. Anonymous, Holloway interview, 2019.

A magazine article or something behind a paywall (rare)

  • Quoting someone from the article:

    • Nash, Courtney. “Coolest Mom In the World,” Pepper Nash. Rolling Stone, 2017.
  • Just citing the article:

    • Nash, Pepper. “Coolest Mom In The World.” Rolling Stone, 2017, San Francisco.

···

Acronyms and initialisms

Include an acronym (something that can be used as a word, like HUD or FIFA) or initialism (what can’t be pronounced as a word, like FCC or ASPCA) in parentheses following the first full usage of the phrase or title. After that, repeat the full version if enough space in the text has gone by that a person paying a reasonable amount of attention could have forgotten what the acronym stands for. Generally, repeat the full phrase or title if it hasn’t been used in 1,000 words. The exception is any acronyms or initialisms that appear as part of a defining occurrence, meaning they will get mouseovers throughout the Guide and so do not need to be spelled out outside of the defining occurrence.

Referencing quantitative data

Numbers one through ten should be written out. 11 and up should be numerals. Do not spell out a range, use numerals instead, as in “Create a list of 5–10 people.”

  • Note: You may see exceptions to this, such as “We’ve seen this happen ten to twenty times.” We don’t yet have a hard and fast rule for this, so if you see it, call it out and we’ll figure out the right usage.

  • Also, an en dash—not a hyphen—is used to show a range of numbers, as in “9–20.”

  • If you’re only using numbers below 10, write it out, as in “one through three” or “one to three.”

Money should always be numerical, as in $3M. (Do not spell out to 3 million.)

  • When using a single letter as shorthand for a quantity, e.g. M for million or K for thousand, the letter should always be capitalized and there should be no space between the letter and the number.

Never spell out percentages, use the % sign. Percentage ranges should always prefer an en dash, as in 5–10%, with the single % sign at the end. Plus signs and approximate symbols are fine, as in $300M+ or ~$300M.

Figures and tables

Thanks to the UNC Writing Center for help with this section.

If you can summarize the data in a figure or table in one to two sentences, do so. If your data are more numerous, providing a figure or table for representation can be helpful and keep text from getting cluttered with numbers.

A table is a columned list of raw data, numbers of text, and is not designed to show the relationship between any variable. Tables should be:

  • Numbered
  • Centered on the page and set apart from the text.
  • Titled, where the title appears on top of the table (Do not rename it if it already has a name.)

Figures are maps, graphs, charts, drawings, or photos. These are what you use when you’re trying to share a conclusion about your data in the form of relationships between variables. Figures should be:

  • Numbered (e.g. “Figure 1”)
  • Centered on the page and set apart from the text.
  • Captioned, with the caption appearing below the figure.

Tip: Keep track of ideas for tables and figures while writing, and share these ideas with your editor. They can work with the engineering team to help produce these.

Definitions37 minutes, 7 links

Definitions are a unique aspect of Holloway Guides and writing, and have their own guidelines, format, and style. They add structure and rigor to the editorial process. They also power features of the Holloway Reader experience, including:

  • Search results
  • Mouseovers
  • Glossary pages

Our goal is to write definitions that are high quality, constantly expanding, and make all of these things possible from the same source content.

Background concepts

Defining occurrences and defining blocks

Definition The defining occurrence of a term (word or phrase) is the first definitive mention of that term within a Guide. Often, the defining occurrence is the first time a term is mentioned, but it may be mentioned in passing or incidentally before its defining occurrence.

The defining block is the one paragraph (or, rarely but possibly, a bulleted item) that has the defining occurrence. The defining block should include one to three (or so) sentences that define the term for the lay reader.

Following a defining block, a Guide can have elaborative text (or follow-on chunks) that gives additional context or information about the term that was defined or about its context or placement within that Guide. Elaborative text is specific to a single Guide.

The defining block may appear in multiple places:

  • Within more than one Guide
  • On mouseovers
  • On landing pages
  • In search results

Elaborative text may appear:

  • In individual Guides
  • On landing pages
  • In search results

Alternate terms

Every defined term can have one or more alternate terms. These might include an acronym or initialism of the term being defined, a shortened version, synonyms, or simply an alternate but relevant phrasing. These alternate terms usually directly follow the defined term in the defining occurrence chunk. They will be supported with mouseover definitions of the defined term if they appear in parentheses, in bold along with the parentheses. In general, use (and bold) “or” within the parentheses if showing an alternate phrase, synonym, or abbreviation; no “or” is needed if showing an acronym or initialism.

  • E.g. “A capitalization table (or cap table) is a table (often a spreadsheet or other official record) that…”
  • E.g. “Annual Percentage Rate (APR) is the total cost per year of borrowing money, including the interest rate, as well as any mortgage points, fees, charges to create the loan itself…”

Sometimes a joint definition is a fine substitute if the words seem different enough: “A founder or entrepreneur is an individual who started a company and now runs that company.

It may be the case that the best phrasing of a definition separates the defined term and its alternate:

  • E.g. “A private company becomes a public company (or goes public) in a process called an initial public offering (IPO)…”
  • Using this example, you will be able to mouseover every occurrence of the phrase “goes public” in the Guide, and the definition of IPO will appear. In the earlier examples, “cap table” and “APR” would bring up mouseovers in the same way.

Joint definitions

Often, only one term will be defined per chunk. But sometimes it makes the most sense to define two terms at once, in contrast or relation to each other. A 🄳 before a chunk that is defining two terms works the same way as with one term. The chunk as a whole, with both terms defined, will come up as a mouseover for either term throughout the text. We call these joint definitions.

  • E.g. “Stock is a legal invention that represents ownership in a company. Shares are portions of stock that allow a company to grant ownership to a variety of people or other companies in flexible ways.”

If a reader invariably will need to understand both concepts at once (in both directions, meaning both definitions depend on each other), it’s best to have a joint definition. In this example, understanding the terms “shares” or “stock” is impossible without knowing about both.

Definition group

The set of all terms, including joint definitions and alternate definitions, is a definition group. A defining block is a paragraph that defines every term in a definition group.

Mouseovers

Mouseovers also allow you to visit the defining occurrence by clicking (or tapping) on the mouseover text itself. (What you just saw there is an example of a mouseover for the definition of the defining occurrence!) This is important because a reader is able to get the context of the defining occurrence if they need it. Users will be able to jump to the defining occurrence (and see its surrounding text) and then jump back to where they were (this may be a forward and back button in the browser, though the tooling may change down the road). Otherwise, a reader can simply remind themselves of the definition using the mouseover feature and move on with where they were in the text.

Mouseovers are helpful because sometimes structure dictates that a term be mentioned before being officially defined; other times, a term may not be mentioned again until a dozen pages after it was defined. A forward mouseover occurs over a term that precedes that term’s defining occurrence. A reverse mouseover refers to a defining occurrence from earlier in the text.

A mouseover refers to the definition of a term appearing as you hold your cursor over the term (desktop) or quick-tap the term (mobile) as it occurs throughout the text.

Mouseover matches will be for the longest matching phrase. For example, “ownership interest” would have a mouseover definition but “ownership” would not.

Some terms are formally defined but are so common (“company,” “property”), we configure them to have mouseovers disabled globally.

Sometimes mouseovers may not occur consistently if two different and related multi-word terms occur in context, such as in “public and private company” or “preferred and common stock.” In those instances, only “private company” and “common stock” would get mouseovers. In cases where a reader would expect both terms to have mouseovers, change them to be the complete terms, as in, “public company and private company” and “preferred stock and common stock.”

Elements of a definition

A defining block is the most important paragraph on the term being defined. It is arguably one of the hardest things to write well, as it should be thorough, precise, and brief.

The defining block begins with defining text, which are the sentences that precisely define what term is and include the term in boldface, possibly with alternate terms. For joint definitions, each of the terms must be defined. The defining text is one sentence in the most common cases, but could be more.

The paragraph continues with text that fills in context, details, and other essential information that goes beyond the defining text but is still essential enough to be mentioned right away.

It’s worth explicitly considering—and if appropriate, deliberately omitting—each of these elements in a definition:

  • The defining text: What is this thing? State this clearly and precisely, usually in one or two sentences. All boldfaced terms and alternates appear here.
  • Synonyms and alternate terms: Acronyms, abbreviations, and alternate terms. Also include directly related colloquial expressions if they are important and not obvious.
  • Context: If there is context to make sense of what it is, include that. Sometimes this goes in the first sentence.

    • For example, is this a term that’s used in accounting, or in venture capital, or in stock trading?
  • Significance: Why does this thing matter at all? To whom? In what situation?
  • Essential background and facts: More background on what it is, such as abbreviated history. Notable examples may be relevant, but only include significant key examples. Do not include illustrations, such as fictional scenarios, which should go in elaborative text (which would go in elaborative text but not the defining block).
  • Essential resources: What resources, if any, are so important anyone learning this term know about them in the definition? Longer lists of resouurces go in elaborative text, but sometimes certain resources are definitive.

    • Examples: If defining Safe financing, a link to the defining documents from Y Combinator makes sense. If defining long-term capital gains, a link to Pub. 550 from the IRS that discusses capital gains is likely the authoritative source.
  • Confusions, disambiguations, and alternatives: Are there things this term is often mistaken for? Are there “similar but different” terms where the relationship to this term is worth clarifying? Are there common alternatives, i.e. things that could be used instead?

Other than the defining text being first, the order is not strict, but it often flows in the order listed. Sometimes some items just aren’t essential, so are skipped.

That’s a lot, but in addition, all this should be done with brevity. There is no hard and fast rule, but aim for one medium to long paragraph, so between three and eight sentences is ideal.

Remember, the defining block is formal—clarity, precision, and accuracy are top priority. Loose commentary, jokes, or levity don’t have a place in the defining block. Elaborative text in a Guide can be used for more informal commentary and illustrations.

What should be a definition?

It’s not always obvious what should be defined as a term. Questions to ask:

  • Is this an established term?

    • That is, is it in actual use either by experts or in popular non-expert usage?
    • If neither, it’s probably a concept or an idea to talk about, but not a concept to define formally.
  • Will it fit with the purpose of definitions in the product? If most of these are yes it’s likely a good term to define:

    • Would mouseovers be helpful?
    • Could we build a definition landing page that people would find useful?
    • Would it make sense appearing in a glossary?

Specifics examples:

  • Yes:

    • Anything defined in an existing reference, online or offline.
    • Any widely popular concept that appears in search results (even if it’s a bit confusing or not the expert-preferred term, we need to make a definition for it).
    • Anything experts would generally agree is a concept (even if the details are a little murky), it’s best if we do define it.

      • Example: Mid-stage (concept a little murky but everyone knows it exists) in the context of company growth.
  • No:

    • The exact phrase isn’t found in books or Google results. In this case it’s likely a concept that might be emphasized as a section title or a boldfaced concept, but not a definition.

      • Example: In context of company registration: “State of registration” as a phrase doesn’t show up places. “Registration” does.
    • Things experts may not even agree is a thing.

      • Example: “Distribution insight” is a term used by the venture firm Floodgate, not by everyone.
    • Things that aren’t defined formally can still be discussed!

What do you do if something doesn’t make the cut but still “feels” like a term? Options:

  • Inline headings (typically boldfaced items before a list of bulleted items)
  • Incidental terms (italics), optionally with a link
  • Boldfaced phrase inside a paragraph to highlight a key idea or phrase

Definition consistency across Guides

Shared definitions

Because subjects of Guides are often related, it’s common that a term defined in one Guide will also appear in one or more other Guides.

When possible, globalize the defining block by making it reusable across all Guides, and readable stand-alone. To globalize a definition, the defining block should not utilize language that is specific to the content of any one Guide. It should not reference its place in any single Guide with phrases like, “Now that we’ve covered X, here’s Y.”

In some cases globalizing a definition is not possible or too much work, which is okay. For these, the definition text in one Guide may be different from in another Guide.

When a definition is globalized, remember that subsequent follow-on chunks can differ in each Guide.

Definition group consistency

Joint and singular definitions, however, should always be consistent. If we define “stocks and shares” together in the Guide to Equity Compensation, they must also be defined together in the Guide to Raising Venture Capital, as joint definitions. If in Raising Venture Capital we define “common stock” and “preferred stock” separately, the terms should not be defined jointly as “common and preferred stock” in Equity Compensation.

Guidelines for writing definitions

Definitions should be the best brief definition available within the context of the Guide, and should include:

  1. A brief, precise definition, close to what an encyclopedia or dictionary might give.
  2. Abbreviations or synonyms.
  3. Elaboration given context—either of a specific Guide or, if a global definition, of the general field in which the majority of Guides fall under. This is essential—what does the term mean specifically in the context of the topic under study?

    • E.g. “Equity” has a different context in real estate than it does in business. Business is a central topic at Holloway, so “equity” can be defined globally by its relevance to corporate financing and compensation strategy. Guide to Guide, follow-on chunks can demonstrate the relevance of equity to whatever specific topic is being covered.
  4. Possible confusions or differentiations, including warnings not to confuse this term with others like it or the same term in different contexts.
  5. Optionally, any facts or examples that are so essential or helpful to understanding that they merit inclusion in the defining block.

Boldface usage

The defined term must be boldfaced. When possible, the boldfaced term should occur near the front of the definition, as well as the defining text (or the clearest single sentence that precisely defines the fundamental aspects of the term). This makes mouseovers easier to digest, and emphasizes what term or terms are being defined.

Any alternates must be boldfaced, along with the parentheses that hold them. If “or” is part of the parenthetical, it too should be boldfaced.

In the case of joint definitions, both defined terms must be boldfaced.

Boldface full terms if the partial term would have misleading mouseovers.

  • E.g. “long-term capital gains,” not “long-term capital gains

Emoji usage

Do not use emojis in definitions. If there is a quality about a particular definition that needs to be pointed out—a pitfall or confusion, say—make an emoji-tagged statement about that quality in the elaborative text.

Style

Because definitions will appear in a glossary, they are generally more formal than the text that surrounds them. They should be able to stand alone.

Avoid first person plural in defining text, as in, “We call this X.”

Avoid the second person in defining text. Explanatory text that follows defining text can be more informal and employ the second person (particularly when a definition depends upon or leads to some kind of action).

If there is explanatory text in the same paragraph as the main definition, but it is situational or otherwise not important enough to always appear inside a definition, move it to a subsequent bullet or paragraph. Remember, emoji tagging can be used on bulleted explanatory text that follows the formal definition of a term.

Referencing other terms

If in a definition you are making use of other terms or concepts that themselves are formally defined elsewhere in the Guide, you can rely on mouseovers of those terms appearing in the definition you’re working on. A definition block should focus on defining one term or on two (or more) inextricable terms in a joint definition, relying on mouseovers for any further terms used to explain them.

A definition will never mouseover the same term already being defined, even if the text appears more than once.

An incidental definition is when a new term is introduced but for one reason or another, we’re not going to define it formally with a full definition. Use italics for incidental definitions, not boldface. That way, a reader should not have to wonder, “Is this really a definition?” Incidental definitions should not appear within the defining occurrence of another term.

Syntactic precision in definitions

Avoid uncertain and imprecise language within defining text. Words like “maybe,” “often,” and “typically” can confuse the reader about whether these are defining characteristics or just commentary. The definition itself should be certain, even if its implications are uncertain. These can always be elaborated on later or even after a clear initial explanation.

For example, avoid phrasing like this: “🄳 Mortgage Insurance (MI) is a type of insurance that may protect the lender in case you fail to make payments.”

We prefer this: “🄳Mortgage Insurance (MI) is a type of insurance that protects the lender in case the borrower fails to make payments. It typically…”

Logical precision in definitions

Be careful about directions of implications so the full sense of the word is clear.

For example, the defining statement “X is a situation where Y” is not the same as “In situation X, Y happens” or “Y occurs when X.” The first is a precise definition since it means “X implies Y and Y implies X,” while the latter two both mean only “X implies Y.”

Yes:

  • “An acquisition is when one company purchases more than 50 percent of another company.”
  • Dilution is when percentage ownership of each shareholder goes down as the number of outstanding shares goes up.”
  • “As the number of outstanding shares goes up, the percentage ownership of each shareholder goes down. This is called dilution.”

No:

  • “In an acquisition, one company purchases more than 50 percent of another company.” (Do other things need to happen as well for this to be an acquisition?)
  • Dilution occurs as the number of outstanding shares goes up and the percentage ownership of each shareholder goes down.” (Are other things occurring too? Does dilution itself mean more than this?)

We prefer not to use external links in the defining sentence, notably to other definitive sources (e.g. Wikipedia or Investopedia). Our definitions should be authoritative, complete, and stand on their own.

···

Verbosity

Unless you really need to, don’t write definitions that unnecessarily “talk about the words” as this gets repetitive and verbose:

No:

  • “The word X means Y.” (No kidding. It’s a word!)

    • E.g. “The word ‘venture’ refers to…”
  • “X is a term that people use to mean Y.” (Does X mean Y? Are people using it correctly?)
  • “The term X broadly means Y when people are talking about C.” (It’s okay, but could be better. What does “broadly” mean? Are there multiple senses of the word? How many? Are all correct? Or is the term just informal and vague? )

Yes:

  • “X means Y.”

    • E.g. “‘Venture’ refers to the risky nature…”
  • “In context C, X means Y.”
  • “X means Y. It is often mistakenly confused with Z, because…”

In cases where terms are themselves confusing, and language and usage need to be discussed, the definition should have a confusion-tagged follow-on chunk.

Be careful about directions of implications so the full sense of the word is clear.

Singular vs plural and noun vs verb

In general we prefer singular nouns. But this isn’t a hard-and-fast rule. Do what makes the most sense and reflects current usage.

  • Example: For company formation, incorporation is the most commonly defined noun.

Product mouseovers will work either way on almost all singulars or plurals.

Examples and facts

Definitions may include key, important facts or notes or examples if they’re relevant to most readers of the definition. But they shouldn’t include illustrative examples that are pedagogical or situational.

Yes: “The tax brackets in the United States as of 2018 are X%, Y%, Z% …” (These concretely specify the tax brackets. And they can be updated later as needed.)

No: “For example, if George makes $80000, he pays $X in tax.” (This is a pure illustration not appropriate for a defining occurrence. It can go as subsequent Guide text.)

Placement of definitions in a Guide

The defining occurrence of a term (word or phrase) is the place in a Guide the defining block occurs.

In our traditional format, the 🄳 emoji is used to indicate the defining block and the defining occurrence, as in the paragraph above. (In the future, the defining block may only appear in another table.)

Often, the defining occurrence is the first time a term is used at all, but it may be mentioned in passing or incidentally before its defining occurrence. The defining occurrence should include one to three (or so) sentences that define the term for the lay reader.

When the 🄳 is added at the start of a chunk of text that contains a bolded term, the annotation will make the chunk (a paragraph or bulleted item) the defining block for that Guide: the block can then appear elsewhere (as a searchable definition, on a landing page, in a mouseover, etc.).

It is very helpful to have the 🄳 readily available to you! Bring up the emoji keyboard by pressing (control + command + space bar). Expand the keyboard by clicking the small box in the top right corner. Copy and paste the 🄳 into the emoji search bar, then drag it into the “frequently used” section of your emoji keyboard. Now you can find it easily.

Don’t define things twice

The defining occurrence should only be in one place. If the reader is already expected to understand a term, avoid re-stating a definition again in similar form a second place. The mouseover will be sufficient.

Sequencing definitions in a Guide

A Guide should be understandable if read front to back, even without mouseovers.

That is, even though mouseovers will add a lot of convenience, we’re not abandoning the editorial responsibility of organizing the definitions.

Structurally this is still like a book in key ways. Thinking about sequencing helps us organize material, have editorial discussions on organization much like a book, and source authors much like a book too—but with the convenience that a lot of language (like “see the section on X”) can be omitted.

Forward mouseovers should be used for convenience but not to dispel confusion.

Defining occurrences should be wherever they best fit common usage by the reader. To consider where a definition goes, ask: If a reader doesn’t understand X, what other things should they be reading about?

Accuracy and Rigor1 links

Everything should be made as simple as possible but no simpler.Albert Einstein (maybe?)

It turns out, no-one is entirely sure who said that. And that’s something we’re keenly aware of at Holloway. We thoroughly research our Guides (and cite every source)—comparing, debating, and when possible, reconciling differing or confounding perspectives. Inaccurate or unverified quotes, ideas, data, or conclusions are anathema to us.

···

Writing About People5 minutes, 1 links

This section is almost entirely from MailChimp’s guide.

People are at the core of what we do at Holloway. Readers, experts, interview subjects, writers, editors, engineers—our Guides rely heavily on all these people and many more. Anything we write should be respectful, compassionate, inclusive, and accurate.

Age

Don’t reference a person’s age unless it’s relevant to what you’re writing. If it is relevant, include the person’s specific age, offset by commas.

  • The CEO, 16, just got her driver’s license.

Don’t refer to people using age-related descriptors like “young,” “old,” or “elderly.”

Disability

When writing about a person with disabilities, don’t use the words “suffer,” “victim,” or “handicapped.” “Handicapped parking” is OK.

Gender and sexuality

Don’t call groups of people “guys.” Don’t call women “girls.”

Avoid gendered terms in favor of neutral alternatives, like “server” instead of “waitress” and “businessperson” instead of “businessman.”

Gender neutral pronouns: When referencing a real person, be certain that you are using that person’s preferred gender pronoun. You can often find this information on a person’s Twitter, personal homepage, or Wikipedia page.

  1. When referring to a person who does not identify with the gender binary, and no personal preference is known or available, we prefer “they,” “them,” and “their” pronouns.
  2. In a series of examples, make sure that not every example uses “he,” “him,” “his.” It is best to alternate between “he,” “she,” and “they” where clear.

Use the following words as modifiers, but never as nouns:

  • lesbian
  • gay
  • bisexual
  • transgender (never “transgendered”)
  • trans
  • queer
  • LGBT

Don’t use these words in reference to LGBT people or communities:

  • homosexual
  • lifestyle
  • preference

Don’t use “same-sex” marriage, unless the distinction is relevant to what you’re writing. (Avoid “gay marriage.”) Otherwise, it’s just “marriage.”

When writing about a person, use their communicated pronouns. When in doubt, just ask or use their name.

Hearing

Use “deaf” as an adjective to describe a person with significant hearing loss. You can also use “partially deaf” or “hard of hearing.”

Heritage and nationality

Don’t use hyphens when referring to someone with dual heritage or nationality. For example, use “Asian American” instead of “Asian-American.”

Medical conditions

Don’t refer to a person’s medical condition unless it’s relevant to what you’re writing.

If a reference to a person’s medical condition is warranted, use the same rules as writing about people with physical disabilities and emphasize the person first. Don’t call a person with a medical condition a “victim.”

Mental and cognitive conditions

Don’t refer to a person’s mental or cognitive condition unless it’s relevant to what you’re writing. Never assume that someone has a medical, mental, or cognitive condition.

Don’t describe a person as “mentally ill.” If a reference to a person’s mental or cognitive condition is warranted, use the same rules as writing about people with physical disabilities or medical conditions and emphasize the person first.

Vision

Use the adjective “blind” to describe a person who is unable to see. Use “low vision” to describe a person with limited vision.

Word List2 links

Yeah, well, that’s just, like, your opinion, man.The Dude, The Big Lebowski

Not everyone agrees on the internet, but here’s how we handle these words at Holloway.

  • beta
  • checkbox
  • co-founder (not cofounder)
  • co-worker (not coworker)
  • double-click
  • drop-down (noun, adjective), drop down (verb)
  • e-commerce (the industry)
  • email (never hyphenate, never capitalize unless it begins a sentence)

    • Cc, Bcc
  • e.g. means “exempli gratia,” or “for example.” I.e. means “id est,” or, “that is.” In general text we prefer “for example,” “like,” and “that is” or “as in” over the Latin, excepting in examples of data.
  • et cetera (if you really have to use it)
  • emoji (singular and plural)
  • front end (noun), front-end (adjective)
  • fundraise (not fund-raise)
  • Guide (always capitalize for any Holloway Guide)
  • hashtag
  • homepage
  • integrate
  • internet (never capitalize unless it begins a sentence)
  • KISS (When referring to the “Keep it simple…” acronym, often in relation to Y Combinator’s Safe)
  • login (noun, adjective), log in (verb)
  • Like (the social media activity)
  • non-profit (not nonprofit)
  • OK preferred over “okay,” except in dialogue
  • online (never capitalize unless it begins a sentence)
  • opt-in (noun, adjective) , opt in (verb)
  • pop-up (noun, adjective), pop up (verb)
  • Safe (Often referred to as SAFE, but Safe is correct in the context of convertible notes)
  • signup (noun, adjective), sign up (verb)
  • startup (not start-up)
  • sync
  • toward(s): Adding the “s” to “toward” and “forward,” etc., is normal in Britain; in America the “s” is elided.
  • tweet, retweet
  • U.S. (over United States, usually)
  • username
  • URL
  • website
  • WiFi

Grammar and Usage7 minutes

Common mistakes, covered.

That and which

Use which when you’re providing information about a noun, use that when you’re pointing it out. E.g. “These rules, which I’m writing for you, are extremely helpful”; “That editor is remarkably arrogant.” This sounds simple, but ignoring this (oft-ignored) rule can lead to grave confusion.

Who and whom

It’s okay if this is hard, but it doesn’t have to be. Who refers to the main subject of a sentence, and whom refers to the thing being acted upon by the main verb; that thing is also known as the object. The easiest way to get this right is to use the substitution rule. If who can be substituted with he/she, it’s correct. Whom can be substituted only by him/her. Use the same rule when deciding between whoever and whomever. “Come and get it, whoever wants it.” “She wants it!” “Can I ever use whosoever?” Only if you’re singin’ Gospel.

Affect and effect

Affect is a verb that means to influence, while effect is a noun, something that was influenced. (Affect can be a noun, and effect can be a verb, but don’t worry about all that. Just remember that you almost always mean affect.)

Further and farther

Many people don’t know this, but there is a difference. Further refers to metaphorical or figurative distance; farther is literal. Toward and towards (and backward(s) and afterward(s) and forward(s)) Easy! Since Holloway is out of California, and California is in America, just don’t use the s. The British edition can use it.

E.g., i.e., and et al.

E.g. means “exempli gratia,” or, “for example.” I.e. means “id est,” or, “that is.” These Guides shouldn’t be so stuffy that you find yourself using these. Try “for example,” “like,” and “that is” or “as in.” Et al. means “and others,” and is usually used in reference to the multiple authors of an academic article, as in, “Frankenstein, et al.” This may come up in your list of citations.

Can you start a sentence with a conjunction?

Yes. “But” and “and” are acceptable! The revolution has been won by rebel forces.

Contractions

While these guides are professional and designed to be authoritative, they shouldn’t be stuffy. It’s okay to use contractions occasionally, particularly when breaking into a more informal tone in, say, a parenthetical or another type of aside.

Cannot, can not, and can’t

This editor is a proponent of separating this common conjunction in the cases that it helps with emphasis. Think of the options here as a line of defense: Can not is serious (“You can not take heroin, Timmy!”), cannot is normal (“We regret to inform you that we cannot attend your wedding”), and can’t is casual (“Dogs are the best; they just can’t help it!”) Can not is also correct when the not is part of another phrase or construction, as in, “Dogs can not only wag their tails, they can dig holes, too!”

Into or in to?

This one just about sticks in my craw, I tell you what! Into and in to are not interchangeable, and often professional writers don’t know the difference. You are going into the mystic. But you go into let your soul and spirit fly. In to is a shortened version of in order to. Now you know!

Site and cite

A site is a place, either physical or electronic. Cite is short for citation:

“This would make a mighty fine site for a sawmill,” said Brent. “Sure would,” said Macadamia. “Let me look up how to build one on the internet. What’s that How-To site called?” “Look up Holloway Guides. Just make sure you cite them in your book about this grand adventure!”

Data: single or plural?

Data are plural, as in “These data suggest that people fight about grammar more on the internet than in person.” Data point and datum (though it is rarely used) both take a singular construction.

Seasons: proper nouns?

When referring to a specific season, as in, “The average investor check size in Spring 2019 was $400B,” capitalize the season. When referring to the mere idea of a season, as in, “I love fall, isn’t it romantic,” don’t.

Company Names

Getting tech company names right can feel like an endless game of Whac-a-Mole (or is it WhackAMole?). Here’s where to look when you’re not sure, and please let us know any that we should add to this list!

  • Airbnb (not AirBnB or AirBnb)
  • AngelList (not Angel List)
  • Crunchbase (not Crunch base or CrunchBase)
  • ExtraCrunch (not Extra Crunch or Extracrunch)
  • PitchBook (not Pitchbook)
  • Product Hunt (not ProductHunt)
  • TechCrunch (not Tech Crunch or Techcrunch)
  • Techstars (not TechStars)
  • Y Combinator (not YCombinator)

···

?
L