Notes and suggestions for writers, editors, and anyone interested in helping to build guides
Updated February 14, 2021
Credits
Contributors
Joshua Levy — Original author
Rachel Jepsen — Editor
Andy Sparks — Editor
This is an evolving set of notes for writers, editors, and anyone else interested in writing or contributing to comprehensive and practical guides that are helpful to readers. Not all books should follow all the recommendations here, but this is a single place to record a range of advice we’ve found helpful in working with authors on Holloway Guides.
What Makes a Guide?
Every once in a while, we find a comprehensive and helpful resource online, and are impressed and thankful. But we’re also surprised. High-quality, long-form, practical writing is rare on the web. Most of what fills our news feeds is written for a short shelf life—fragmented, with a second agenda like selling us something, or optimized for clicks and ad impressions.
What if we could could create a truly helpful and comprehensive resource, or guide, on a complex topic? Guides have a single purpose: To help the reader navigate complexities. A guide aims to be the best single place to start or return to when a reader is interested in the topic it covers, on or offline.
Practical guides like this are of immense value to people who would otherwise find that information difficult or impossible to find. Of course, long-form reference works take time and effort to write, and require contributions from multiple people over time. Such works are more traditionally produced by book publishers and sold as paper or e-books, and occasionally revised with subsequent editions. However, with maturing web and software tools, it’s technically feasible to make frequent updates and improvements online to a published work.
At Holloway, we are designing editorial processes and an online product, the Holloway Reader, that makes improvements to a guide possible more easily and with the help of more people, while maintaining the high quality traditionally expected of print books. We call this approach iterative publishing.
To see what this looks like, visit our Guide to Equity Compensation. We do not expect that every guide will imitate its style or form exactly, but this work gives an illustration of our format and the product’s possibilities.
The reference content of a guide is different from other nonfiction writing in several ways:
Practical orientation: It offers helpful guidance. In addition to covering situationally relevant material, a guide should give the reader the foundations to build future knowledge and capabilities.
Technical or complex subject matter: This kind of writing is of greatest value when the topic is complex and takes commitment to learn. An abundance of pitfalls, confusions, and important details mean years of training or experience are necessary to become an expert in one of these topics.
Ambitious in detail and scope: The goal is to provide the most credible resource available.
Built for recurring use: A guide is like a reference book with a long shelf life. It’s not a blog you forget after two or three hours, or a read-once bestseller you’d give to a friend after you finish it. Nor is it like the biology or macroeconomics textbook you eagerly sold after passing the course. Reference works are for recurring use—that is, a guide continues to be of use for a single person over time as they encounter different problems and questions.
Built to improve: On complex and nuanced topics that are subject to change, no guide is ever perfect. Rather, it must be built to improve over time, not be published as the fixed work of a single author. Readers may return when there are updates or alterations.
The work of more than a single person: Building a credible reference work requires multiple, varied roles, including authors, editors, expert reviewers and contributors, and production support. It’s not a blog post or a one-writer effort, even though writing may be led by just one or two people.
Supported by product features: In its most useful format, a guide is partly content and partly software; it must be searchable, navigable, and possible for readers to engage with (through comments, bookmarks, and highlights).
It’s worth differentiating a guide like this from other kinds of nonfiction writing. A guide is not:
Historical or narrative nonfiction.
Writing devoted to a single thesis, such as blog posts or popular trade books that argue for a specific policy or focus on one trend.
Writing that is primarily for entertainment.
Celebrity-oriented or biographical nonfiction that is mostly of interest because of who is writing or being written about.
It also helps to differentiate from other online resources. A guide is not:
Wikipedia, which is an amazing resource but is restricted by editorial policy to cover purely consensus facts, where practical or highly specific information is typically not allowed.
Stack Overflow or Quora, which are reference works created solely by user questions and user responses. These resources give single answers to specific problems, not the comprehensive overview, packaged in a trustworthy way, that a book or other credible reference work can provide.
Roles and Working Together
The highest quality editorial products require the efforts of people with different knowledge and skills. Many experts struggle to write well, and even the best writers need editorial help and feedback from readers. Quality writing is the result of people playing several roles, including writers, editors, experts and reviewers, and engaged readers who ask questions or give suggestions for improvement.
Traditional publishing has required distinct roles like this for centuries. But in the era of blogging, we need to emphasize their importance. In practice, some roles are paid and some are not. Often one person, the original author, does a large share of the work, with key support from one or two editors. Then a variety of reviewers offer guidance, ideas, corrections, and improvements.
The process involves a few phases, but overall the main points to keep in mind are:
Content is open to improvement: What we publish is for reference use, and the best references pool the knowledge of multiple people, and incrementally improve over time. The effort of covering complex subject matter is bigger than any one contributor. Unlike fiction or narrative writing, where we expect the original integrity of an author’s work to be preserved, the contents of a guide are not permanently “owned” by a single author. Even if a single author may have done the majority of the work, they and the editors are open to contributions from others who can improve any portion. The writing process itself also involves feedback: it is most effective when authors and other contributors talk to readers when planning and researching, as the draft takes form, and after publication. (In fact, without engaging with beginners, experts often do not know what to write about.)
Content is reviewed: Openness to improvement does not mean any contributor can change anything (as is typically the case with Wikipedia). The original authors and editors work together, enlisting experts for discussion and review along the way, both during the editorial process and after release. Expert review is essential for context and correctness on complex material that is not simply re-stating previously published, verifiable facts.
Contributors are credited: Although people play different roles and contribute different amounts, we do our best to give credit to everyone in a way that fairly represents their contributions. Note that this document is mainly for authors and editors, but we solicit contributors of several kinds to a guide. Contributors are chosen for their expertise, writing ability, and availability.
Principles
It’s worth remembering that all writing and editorial work is in support of some basic principles:
To offer helpful guidance
…with long-term value
…that is trustworthy
…and accessible.
Each of these items has a number of implications for the way authors, editors, contributors, and readers work together. When we write with these larger goals in mind, we find a number of guidelines begin to emerge.
Practical Suggestions for Authors
Don’t skip groundwork: talk to potential readers, and research common questions, so you know you’re writing something that will be useful in the way you hope. Research and ask everyone you trust for what related works are already out there.
Write and share drafts early, in any form—as a blog, newsletters, or simply as a messy Google Docs with your friends.
Get help, feedback, and contributions from experts who have deep understanding of the subject both early (when it’s taking shape) and late in the process (for subject matter review).
Reference writing is easier to accumulate over time, a bit here and there. A lot of the work can be put in whenever it’s convenient, and whenever an idea, resource, or item comes to mind.
Remember no one writes perfect English, and that’s fine. You’ll need copy editing and proofreading help, as with any book. (If you work with Holloway, we handle this.)
Guidelines
The guidelines we cover here are not detailed instructions or hard-and-fast rules. We’ve found that certain ways of thinking are useful in making practical reference writing deeper, more helpful, and more engaging. Having these suggestions in mind can help with the hard choices that come with each phase of the writing process. (The items here are themselves evolving, and we would like your feedback and suggestions on how to improve them.)
The items we cover here:
Make deep coverage accessible.
Earn the respect of experts first.
Start from the beginning.
Imagine readers that are “100% intelligent and 100% ignorant.”
Cover the facts that are helpful.
Consider diverse experience and expertise.
Give frameworks, not answers.
Help people see what they don’t know.
Link or cite pretty much everything.
Broker attention helpfully.
Address multiple, related audiences.
Intrigue readers right away.
Make Deep Coverage Accessible
Some classic reference books are respected and full of detail, yet hard to read for anyone who’s not an expert. Other books are engaging but oversimplify and omit details.
Our aspiration in writing guides is that they be both deep and engaging. Technical and accessible. This is hard to achieve, especially for highly technical material, but we believe it is often possible and as a goal orients our writing efforts.
Both big ideas and technical details are essential for maintaining the attention of experts and novices, and both are needed to truly help readers learn how to think more clearly about a problem. Ideally, a guide weaves details together through foundational concepts and broader ideas—even a little context goes a long way. Another way to look at it is, we want to earn respect from both experts and beginners. Can we help both novice and expert learn (different) things quickly?
A few specific strategies:
Start a guide with zero assumptions about what a reader knows, so anyone can start reading a first section easily and skip ahead if it’s too basic.
Try to present information that would earn respect right away from experts and beginners, by combining fundamental concepts and brief overviews with deeper technical detail. Liberally add introductory sections and introductory paragraphs and sections. But equally, include highly technical points that are important, even if beginners may find them hard to follow (and link to further detail).
Use section titles that guide the hurried reader to something of interest.
Emphasize key details right up front in a guide, such as with surprising but helpful statistics.
Be specific and give examples in the same place you state a general principle.
Emphasize holistic, clear overviews or diagrams that make something complex more understandable.
Emphasize confusions, overlooked suggestions, pitfalls, and misunderstandings that are common. Our use of block styling (discussed later) can make these stand out.
Emphasize balance and context, giving helpful or overlooked alternatives to commonplace thinking.
Use technical terminology and jargon whenever appropriate, but also always define the terms clearly.
Include graphics or diagrams that give a lot of perspective and depth. What kind of diagram would impress both a beginner and an expert?
Give helpful or illuminating historical background that many may not be aware of.
When successfully used, these kinds of things help both credibility (so people trust a guide) and virality (so people are inclined to share or recommend a guide to their friends or professional connections). They are part of what makes a great guide stand out from average content online. Trying to impress beginners and experts at once is hard but makes a guide appealing to more people, and encourages engagement and contribution at all levels.
Earn the Respect of Experts First
A lot of technical and practical writing is written for and read by people who are just beginning to learn about a subject. But the authority of any reference rests on the opinion of experts. Even elementary material can and should be explained in a way experts consider credible.
For this reason, every guide first and foremost must earn respect from the most experienced and authoritative people in the relevant fields. Accuracy, precision, and clarity in their estimation is the first goal. Accessibility can come next, but never when it compromises credibility among experts.
Two key things help make writing credible to experts:
Technical vigilance: Be accurate, precise, logical, and clear. And be explicit when there is uncertainty or controversy. When it comes to this, we can’t compromise.
Stylistic clarity: Even aside from technical accuracy, experts are remarkably sensitive to the style of writing, including any secondary signals an author sends, such as by not focusing on details, overlooking exceptions, not conveying context, over-marketing or over-generalizing.
The last point highlights a key risk: it’s easy to over-state expertise or slip into marketing-speak (“our amazing guide unlocks secrets and tells you everything you need to know!”) or gloss over details or confusing nuances (“just remember these five tricks!”). We must be ambitious enough to aim to be comprehensible and credible, but equally as writers we stay humble. If the topic is complex enough to deserve a guide, it’s imperfect and iteratively improving.
In practice, getting these right requires involving expert reviewers all along, including early in the process of writing as well as later when drafts take shape.
Start From the Beginning
A common mistake for a knowledgeable person, when they outline a guide or begin to write, is to “start in the middle.” By this we mean writing at the level or perspective they’re most comfortable with, without relating that knowledge to a topic’s foundations or broader context. It’s easiest to write for someone with a similar level of expertise to yourself. A comfortable place to start for an expert is rarely where a beginner or someone with different experience would wish to start. This is sometimes called the “curse of knowledge.” Cognitive psychologist Steven Pinker has discussed it in his own writing advice.
So when outlining and writing a reference work, start from the beginning: the foundations or first principles, background information, readers’ motivations, and the significance of the subject. What is most helpful is a careful and logical organization of concepts and sections, beginning with foundations and working toward more advanced ideas, with details inserted liberally.
Of course, it can be convenient and a great idea to “start in the middle” when first assembling your own notes. You just need to backfill the foundations when you return to the groundwork phase (covered more later) and outlining.
Imagine Readers That Are “100% Intelligent and 100% Ignorant”
A useful heuristic is to imagine your readers start out 100% intelligent and 100% ignorant. Of course, in reality, most people may already know something, and some people are quicker learners than others. However, making this assumption has important advantages:
It reminds you, as an author, to start from the beginning, without assuming too much knowledge. You are more likely to outline from foundations up through advanced topics in logical order.
People with varied levels of knowledge can start early and skim forward, and fill in the gaps in their knowledge. This style of outline is most useful on average, since everyone can learn something, and beginners can see everything they don’t yet know.
It fits a broader audience, since people with varying levels of experience or different specific questions can more likely find the information they need—especially when given good search capabilities.
It avoids a trap some technical writers may inadvertently slip into when trying to reach a broad audience: “writing down” to beginners by seeming condescending or over-simplifying important details out of fear they will confuse a novice.
Embrace essential complexity of topics.
Details matter. As Einstein possibly said, “Everything should be made as simple as possible but no simpler.”
Wikipedia is the #5 site on the internet and its pages are filled with complex and technical details. The average Wikipedia reader is 25 years old. The average contributor is 27. There is no need to oversimplify.
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. (See “Brokering attention helpfully,” below.)
If you respect the reader, the reader will respect you. We must 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. In addition, writing with clarity and intelligence makes readers feel capable, and proud of being associated with a guide. If they have to push themselves a little to keep up, it’s often just fine, particularly for important and complex material. (There is indeed a risk of scaring some people off altogether, but we can often mitigate this risk with other product and content choices.)
Cover the Facts that Are Helpful
So if we do start from the beginning, does that mean covering every possible basic fact? How do we decide what is in scope for a guide?
The priority is to be helpful, not only factual. Guides need to cover a lot of facts, and may include many foundational sections exclusively devoted to facts. But the ultimate goal is to serve the reader helpfully, and this determines what factual information is relevant. The value of a guide is in curating facts with actionable guidance in mind.
In general, actionable knowledge rests on factual knowledge. It’s helpful to cover the foundations and context that will support future learning. The reason we often undertake formal studies is that there are large sets of fundamentals that must be clear for later learning and proficiency. Having a firm grasp of the mathematics of compound interest is not essential for every investment decision, but it can help in so many situations that learning it well early on will pay off later.
Consider Diverse Experience and Expertise
We’ve already talked about how the audience of a guide may be diverse. It’s also essential to consult with a variety of people with different experience when doing research and assembling information.
Capture diversity of experience by talking to and soliciting contributions and feedback from people with different practical experience and roles or responsibilities.
Lawyers, investors, and founders can have remarkably different perspectives on a topic like equity compensation. Academics and industry players can have widely variant thoughts about the housing market.
People who work in the same role for different companies can also have very different outlooks on their industry; employees of Walmart and Amazon may fill a similar role and serve a similar market, but their perspectives are likely quite different.
Another variable is the roles people fill at their place of work. Managers or individual contributors, hiring managers and candidates, engineers and marketers—each of these people have different perspectives and concerns; conversations with a variety of players during the research process can make an enormous difference in gaining perspective and conveying a subject’s real complexity to the reader.
It is also essential to converse with people across the spectrum of expertise. To understand and meet their needs, we talk to both beginners and experts during the writing process.
Varied experience exists within an individual as well. For some subjects, world class experts may still only know one component or subfield of a larger topic, or only have practical experience in one type of related job.
Expertise also varies over time. Individuals might come to a guide to get the basics and return later, when they know more but need help with a specific problem.
Give Frameworks, Not Answers
Many readers come with a question and expect an answer. But for harder questions, simple answers are usually not what people need.
If you go to a lawyer and ask if your new company should be a C Corp or an LLC, or go to a doctor friend and ask if you need back surgery, the expert will not just give you an answer. On complex and important decisions, experts usually turn around and ask you the right questions, to understand the real elements of the problem and then help you decide what’s right for your situation. They give you context on how to think about the problem and make decisions.
The most helpful guidance on important decisions is neither too assertive (fully prescriptive and just telling you what to do) nor too passive (waiting for you to make decisions you’re not informed enough to make well).
Note that in contrast, giving answers is often the goal of search engines like Google (or other software like knowledge bases or conversational AI systems). These typically aim to give answers regarding consensus facts.
If you ask Google for “capital of Poland” or “weather in New York” it has an immediate correct answer. This is great for consensus facts.
If you ask Google “How do I get an internship?” or “Should my business be an LLC?” there is no correct answer.
It is only a mild over-generalization to say “experts don’t answer questions.” Like the best experts, guides should give people the frameworks to make their own decisions.
Cover Controversy
With many subjects, there’s no clear answer, and sometimes, there’s not even a recommendation. In general, when there is broad agreement, give recommendations. When there is controversy, give an overview of key perspectives, reference the key people or resources on different sides, and give rationale and context. Things to include:
Key points on different sides of an issue.
Key citations.
If there is broad agreement on some parts, give recommendations.
To the extent possible, include the facts and frameworks needed for the reader to make informed decisions or form opinions. Often, experts can agree on a clearly articulated framework for making a decision, even if they don’t agree on specific recommendations in a single situation.
Help People See What They Don’t Know
One of the most helpful things you can share with someone is a sense for what they don’t know—indeed, what they didn’t even know to look for. When someone says they want to learn more about entrepreneurship or neural networks, they shouldn’t have to already be aware of the key components of those complex subjects. The first goal of a guide is to give those new to a subject the broad outlines of what they don’t know.
The table of contents and section names should be a strong indication of scope and help show a reader quickly what they are unfamiliar with and what they can hope to learn. This is the beginning of fluency.
This is one of the reasons great books are so helpful—an author has spent years deciding what to cover, and the outline often includes areas that many people wouldn’t even think to mention at first. (Yes, we do now have to mention unknown unknowns in the Rumsfeld matrix.)
Examples:
A great table of contents that has a surprising but helpful section.
An infographic that goes broader and deeper than most online visuals so that even an expert learns something.
Inclusion of dangers and pitfalls, as opposed to just outlines of facts and recommendations.
Listing and dispelling common misconceptions.
Link or Cite Pretty Much Everything
When writing for the web, links matter! It’s easy to write without adding links, but far more helpful to do the work of finding what links are going to help the reader.
Reasons include:
Often readers don’t know they want more information, but by making the link easily accessible, they can dive in more deeply and discover something unexpected and helpful.
On the web, having the links conveniently located pulls useful content closer to the reader. In the Holloway Reader, links have mouseovers with snippets that summarize the source or its content without clicking, and pages that are linked appear in search results.
We build good will and give credit where it’s due by citing the work of those who deserve it, as well as website or Wikipedia pages of the experts we mention.
Often writers who plan to publish offline or in e-books don’t worry as much about links. But we need to. Online journalists and content writers are often trained not to link to other websites, because media properties are protective of their traffic or the SEO impacts of linking. We do not believe pushing ads or traffic should be a core metric, and we link wherever is most helpful for the reader.
There are multiple kinds of links to consider:
Recommended links: Resources that are useful, widely known, or well-regarded are explicitly called out in the text with an inline link and some context, like who wrote or produced the resource and why it’s important. Famous books, definitive blog posts, and helpful tools fall into this category.
Elaborative links: Links that give more detail or more context on something we mention. For example, Wikipedia articles on key concepts are usually elaborative. These are less essential than recommended links, but are likely of interest for anyone concerned with that specific concept. They usually need not include any other context where they appear other than the inline link itself, within the sentence.
Pure citation links: When verifying a fact or providing the source for a statement, use a link as a citation by putting it in parentheses, with the source name as the linked text, following the information being verified. (We will make pure citation links less prominent in the product in the future.)
Guidelines:
For each sentence or paragraph you write, ask yourself, what are the best links giving detail on this?
For each link you add, ask yourself, is this really a good link, or is there a better one?
Multiple citations are better than a single one, if they each have some value, and especially if we can synthesize a helpful summary from two or more sources. This is like saving the reader multiple Google searches.
With these links we can build useful future features, too, such as “external search”—search results from pages we link to.
Broker Attention Helpfully
Our job in writing guides is to earn the trust of readers, which means brokering attention helpfully.
Publishing houses, search engines, and media brands are all attention brokers—they mediate between people and businesses who provide content, and readers who consume it.
Different online media broker attention differently, sometimes in ways users really like and sometimes in ways that deeply frustrate them.
Obtrusive ads, clickbait, and popups broker attention in ways that are not helpful for the user.
Even when users are voluntarily devoting their attention to something, they are not spending that time any other way. They notice this over time, and decide the value of media based on whether it feels valuable. Think about reading a great book versus idly clicking on Facebook.
How does this apply to writers? The job of a guide is to help the reader allocate their time in ways that are most effective. This has a lot of consequences:
The volume of written words on different subjects should roughly reflect likely importance to readers.
The topics covered should reflect demand—the information the reading audience really wants.
Topics that are very important, even to a small group of people, should not be omitted.
Including context and information from many sources saves the reader time of doing that research themselves.
Sometimes readers ask for one thing but find other things helpful. If lots readers are searching for information about Paleo diets, these same readers could benefit from learning about nutrition in general. So the most helpful guide would mention and give context on both areas.
Pitfalls and misperceptions are just as important as straightforward facts.
Address Multiple, Related Audiences
Know your audience. But don’t narrow your audience. Unlike a customized blog post written to meet the needs of a specific reader, guides are built to reach different kinds of readers with different needs.
This doesn’t mean writing for absolutely everyone. A shared resource is possible and can be of extraordinary benefit to multiple, related audiences who normally find themselves on different—sometimes opposing—sides. A Guide to Equity Compensation can be written for employers and employees, a Guide to Venture Capital for investors and entrepreneurs, a Guide to Databases for database experts and regular users.
Why?
There are many good reasons reference content should be written for different kinds of learners with different relationships to a particular topic. Most importantly, it helps readers navigate where information asymmetries and incompleteness has made it difficult for people to communicate and relate to one another and empathize with the other’s motivations. This all makes it near impossible for any one person to understand the topic fully.
Reference works are expensive to build so it makes more sense to have the content be shared.
It forces deeper discussion during the editorial process. Writing about compensation with both employers and employees in mind drives us to cover differences of opinion more during the writing, and express complexities more clearly for everyone.
A shared resource is valuable for those who find themselves on opposite sides of the table. Employees and candidates may be the largest set of readers of the Guide to Equity Compensation, but employers and hiring managers refer to it as well. It can be of great benefit for both sides to know they’re operating with the same set of information. Employers can even refer employees to it, relieving themselves of the responsibility of conveying complex and important concepts well.
Intrigue Right Away
A final goal is to help people appreciate a guide’s value right away. If you don’t capture attention quickly, you might not get it at all. Once you have a reader’s interest (and respect), they’ll pay a lot more attention.
There is a simple test you can apply, called the 30 second rule: Does what we offer make people, no matter their level of experience with a topic, lean in to a guide right away?
When skimming from top to bottom or bopping around through the table of contents, is there enough detail, clarity, and logical structure that most people, even experts, say, “Oh, interesting” or, “Aha…”?
A beginner should be impressed with the volume and depth but not too intimidated to start reading.
An expert should find details that earn their respect.
Readers of many types should lean in and find “nuggets” or helpful or thought-provoking details.
This is what makes content so good it’s viral. But not viral in a quick or hacked way. We are not tricking the reader into caring. This is not about being provocative or sensational or writing clickbait (“5 easy steps to your first million!”), nor is it about pure entertainment, like memes or cat videos. Without oversimplifying details or writing for short-attention spans, we aim to organize a guide 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.
Groundwork
The quality of the guide is dependent on what we call groundwork, which is the initial research phase. Groundwork consists of a series of background and preparatory questions to answer in order to build a thoughtful outline of everything that should be covered in a guide. The groundwork questions fall into three categories:
Scope: Scoping consists of deciding what’s included and what’s not (and what is referenced but not covered in depth), and determining who is likely to make up the multiple, related audiences of a guide. This includes clarifying portions that are not within the scope, or audiences that are not being written for.
Significance: Why a topic matters, where and how it is discussed, and its myriad connotations.
Research: Scenarios, questions, terminology, people, resources, and past works that are relevant to the topic.
Groundwork is crucial and should begin early in the process of writing. The more time you spend scoping, doing research and assembling resources, and understanding context and previous work on a topic, the better the resulting guide will be.
Scope
What will be covered?
What will not be covered? Consider also what will not be covered in this release of a guide, but can be covered later.
What are the reasons you could see a reader coming to this topic?
What are the 5–10 most common entry scenarios that might bring different readers to a guide? Consider what problems or questions they might be facing.
For the guide to Equity Compensation, entry scenarios include “Quitting my job and need to decide whether to exercise my stock options” and “Got a job offer and need to know what I can negotiate around equity.”
What are some likely but misguided reasons a reader might come to the topic, perhaps based on misunderstandings of the topic?
For a guide to Nutrition, a misguided entry scenario could be “Want to lose five pounds a day.”
Who is this for?
Are there multiple, related audiences that could be addressed?
Are there any groups of readers who should be excluded?
For example, those working outside a specific industry or outside a specific country or legal jurisdiction?
Are these groups different stages of learners?
For example, both students and those in the workforce?
Are there different groups of readers playing different roles related to a topic, where each could benefit from the other’s experience?
For the guide to Equity Compensation, this could include employers and employees. For Buying a Home, buyers and sellers have complementary perspectives.
Significance
Significance to the author(s) and the editorial team:
What is your personal relationship with the topic? How did you (or we) come to be interested in the topic or a knowledgeable resource for those interested?
Significance to individuals:
Why does this topic matter in concrete and immediate ways to readers?
To whom? For example, if it is the Guide to Buying a Home, how many people buy a home every year, and why? What factors affect their decision? How many people sell a home? What are the reasons they choose to sell?
Significance for professionals:
For what typical roles and companies is knowledge of this subject necessary or helpful?
Academic significance:
Is this subject typically taught in college or graduate school? When?
Is it an area of academic research? Do people get PhDs in fields relevant to this topic? If so, what do they research?
How does academic treatment of the topic differ from industry use?
Emotional and popular significance:
Does this topic come up a lot in discussion, and if so, where? With friends, at parties, on social media?
When it does come up, what are the typical emotions at play? Are people excited, worried, angry, upset, confused, bored?
Is conversation around this topic approached with urgency or distress, with statistical evaluations and equations, with questions of morality?
Decision-making value:
How does knowing about this topic affect each of the groups of people who need or want to learn more?
Are costly mistakes made? Are decisions made by individuals, families, groups, companies, or governments?
Think about whether someone might say how their life could have been improved if they had known more about this topic ten years ago. How will a better understanding of this topic help readers protect themselves from unnecessary financial losses, costs to their health and relationships, and lost time?
How can different people properly understand relevant opportunity costs?
Significance in news or public discourse:
Is this topic covered in the news or media? How is it marketed, researched, or politicized? Examples?
Which modes of persuasion are typically used in discussion? Is it often logical and factual, emotional or anecdotal discussion, or is discussion guided by specific authorities?
Timeliness and historical significance: Is there a reason this topic is particularly interesting now or has been recently? Or is it growing in significance, with some big shift likely coming soon?
Are there major or overlooked events, statistics, or facts about this topic or a component of this topic? Is now an interesting time, historically speaking, when it comes to this topic?
Have any inventions or discoveries come out in the past year that might drastically change the scope of this topic? Is there an emerging body of knowledge on this topic that would make it particularly exciting, challenging, or important to work on?
How have people’s thoughts (both popular and expert opinions) evolved over time on this subject? This material can provide a great deal of context on the present and future content of a guide, and depending on the topic, consider including a section devoted to a brief history of the topic.
Historically, how much and how often has thinking changed?
When have experts been right or wrong in the past?
Global significance:
What are the more global social trends that are affected by having or lacking knowledge of this topic, or that affect or are affected by consensus or controversial understanding of this topic?
How does it differ by language, culture, location?
Authorities:
What authorities exist around this topic and why are they significant? Individuals, companies, NGOs, governmental bodies?
Are these the same across different countries and regions?
If you could recommend just one or two people to talk to about this topic, who would they be?
Significance to companies or financial interests:
Do specific products or companies benefit by providing goods or services related to this topic? Which? What are their relative sizes and importance?
Do whole industries exist that support people in this area?
Think of personal financial managers or taxation advisors for a topic like Personal Finance.
Are there professional groups that support those industries?
Think of real estate agent associations or contractor unions for a topic like Buying a Home.
Economic significance:
What parts of the economy are linked to this topic? How big are they relative to other parts of the economy?
What are its economic influencers and influences?
If writing a guide to nutrition, consider how nutrition-related illness affects the healthcare market.
How does the topic affect people in different socioeconomic circumstances?
Community significance: What communities are affected by this topic, including communities affected by having or lacking knowledge or access to knowledge on this topic?
How has this knowledge been or not been made accessible to certain people? Is this topic taught in schools? Is it sequestered within “in” communities? What is the traditional makeup of experts of practitioners in this field? Why?
Are any communities adversely affected by components of this topic? Consider geography, ethnicity, race, political orientation, sexual orientation, gender identity, background, and economic circumstance.
Questions and Entry Scenarios
What are 5–20 most fundamental questions about this topic? If you knew nothing about it, what would you ask?
What are the 20–200 most common questions about this topic?
Source them from web searches, readings, Quora, etc.
More on how to source and organize these.
From people and potential readers.
How do the questions divide into entry scenarios? Is it possible to list the scenarios and assign them to the most common questions?
Terminology
Assemble the key terms, key concepts, and key figures and entities.
Change, Confusion, and Controversy
Ask yourself these questions. And then ask some experts, too:
What are some of the most confusing areas of this subject for typical readers?
What are some of the most frustrating areas of this subject for you? For others you know?
What are the fastest-changing areas of this subject?
What useful secret do you know about this topic few others know? If there were two or three things about this topic you could get everyone to know, what would they be?
Process
We needn’t get into every detail as it varies, but a typical set of milestones for authors and editors looks like this:
Editorial checkpoint, expert review and discussion
Chapterwork (writing sections, possibly with help of experts)
Editorial checkpoints and iteration as needed
Expert reviews
Iterations
Production edits
Copy editing
Formatting, tagging, definitions
Graphics
Iterations and improvements based on reader feedback and engagement
Depending on what’s agreed on in the editorial production schedule, it can also can make sense for larger works to insert one or more public releases part-way through for individual sections or segments of the guide—that is, multiple publishing dates per guide.
Tools
Traditionally, authors use whatever tool they most prefer to write, often using word processors like Microsoft Word. At some point, a publishing house takes over the production of the manuscript and uses its own production tools.
We’ve found that in a more collaborative and digital environment, different tools are helpful for each phase of the writing, from initial groundwork, outlining, and drafts, to expert contributions, to production edits.
The process is flexible, but we currently recommend a combination of a few tools, as a guide evolves:
Early research and authoring in Google Docs or Notion. Both tools allow instant sharing and feedback, and allow you to view and work on your laptop or mobile device. Until the writing on a section or the whole guide is nearing completion, this is usually sufficient.
At Holloway, ongoing management and production editing of the manuscript is handled using GitHub and Markdown. Authors are not required to master these more technical tools, but editors and copy editors must, and we encourage everyone interested to give them a try. We use and recommend the Atom editor for Markdown editing as it is most powerful (and also the Flowmark plugin for Markdown formatting).
Formal review and expert feedback via Google Docs. This happens after the “authoritative” draft is in GitHub. It’s possible to make individual copies for each reviewer, and have them make comments or use the track changes feature to suggest edits. These are then folded back into GitHub.
Once a guide is public, the Holloway Reader (discussed next) allows reading, search, suggestions, and other feedback, and these are handled in the product and with subsequent revisions using the above tools.
The Holloway Reader
The Holloway Reader is the most full-featured way for readers to engage guides on the web, on desktop or mobile. See the Guide to Equity Compensation to explore the Reader.
Some of the features of the product are visual or user-experience related only. Others are content-related and do affect writing and editorial processes. The key ones are:
Navigation:
The table of contents is visible on desktop and mobile, and two levels of section headings make it relatively quick to find what you’re looking for, if the section headings are descriptive.
Block styling:
Specific paragraphs (or bulleted items) can be tagged with emoji that express a special meaning. These trigger formatting rules that help call out the type of content. The set is extensible but includes:
important important Important and often overlooked tip
danger danger Serious warning or danger (where risks or costs are significant)
caution caution A caution, limitation, disadvantage, or quirk
controversy controversy Controversial topic where informed opinion varies significantly
confusionconfusion Common confusion or misunderstanding, such as confusing terminology
technical technical Technical point (arcane or academic and not essential)
new new New or recent developments
incomplete Expansion or improvement needed (please help!)
Definitions mouseovers:
In a guide, definitions are paragraphs (or bulleted list items) that are tagged by the author as being the “defining occurrence” of one or more terms. This is much like a technical or math textbook that formally marks definitions.
Unlike a paper book, these definitions have special meaning: The definition paragraph itself will be available to the reader (as “mouseover” box that hovers over the defined term) wherever it appears elsewhere in the text.
There are nuances on how this works in practice, but the basic idea is to mark each definition paragraph with a special emoji indicating that that paragraph is a definition, and then boldface the term or terms defined in that paragraph. The product takes care of the rest.
Search features:
Keyword search: It’s easy to search the text of the guide itself.
Section and definition search: Sections and definitions appear within search results as well, which means it’s often a good idea to include key ideas or concepts in section headings or as definitions.
External search: The contents of all linked content is also searchable.
Marginal notes:
Readers can add marginal suggestions or notes to the guide. These stay in place even if a guide is edited or changed. They are typically private but can also be made public or archived by editors.
Bookmarking:
Readers can bookmark items or highlight text. Bookmarks are generally private unless readers share them or it’s approved by editors to be public.
Anecdotes:
Additional posts or augmented material, such as an interview or blog post, can be attached to a guide to augment the main guide content. This is a bit like writing a more personal Medium post and linking to it—but in the product itself.
Highlighting:
Readers can highlight sections of text and make notes associated with them. Highlights will generally be private unless readers share them or it’s approved by editors to be public.
Concerns and Pitfalls
This is a short list of the common concerns, questions, and pitfalls we’ve seen with guide writing so far.
Common Concerns
We often have conceptions from other kinds of writing, from blogs and narrative nonfiction to Wikipedia articles, that do not apply when writing guides. Here we address some of the questions and confusions that come up most often:
“We shouldn’t cover X because it’s controversial” or “This is too subjective so we shouldn’t write about it.”
Yes, we probably should! But in a way that is helpful and promotes understanding.
Give factual basis around the controversy: Who argues what, and why? What do statistics or polls say? Do respected experts disagree, or are there mostly uninformed but popular misconceptions? Is there a dichotomy between academic or expert opinion and popular opinion? If you dig deep enough into reasons for disagreement, could you come up with a framework that reconciles those differences?
Give context: It’s a guide’s job to give people historical context, too. Has opinion changed over time? Is it likely to change again?
On forums or Stack Overflow, flame wars are a major pitfall. We are not a discussion forum, so this isn’t as much of a problem. We defer to experts and can say things some readers may disagree with; if disagreement is fierce it will be apparent in comments or suggestions and the content likely should evolve.
“We shouldn’t cover X because it’s just a fact you can look up, not practical or actionable.”
Actually, we should cover lots of facts, if they’re relevant. It’s the analysis and processing of those facts that leads to expert insights that are useful.
Facts truly irrelevant to the topic should of course be omitted, but our job is to include all the facts that matter to the readers. This can mean both covering the necessary facts in depth and referencing more tangential details with brief mentions and links.
“We shouldn’t cover X because it’s outside of the scope of this guide.”
For any topic like this, consider whether we should (1) mention it or reference it, (2) cover it in depth, or (3) ignore it completely.
In cases of doubt, the right answer is usually (1) and sometimes (2), but rarely (3). If a reader is likely to expect something might be in a guide, we should address it. But probably not in comprehensive form, possibly redirecting them to what frameworks of thinking or line of questioning might be more appropriate to the topic and/or more in their interest.
This is also important as we collect demand and interactive search data.
The guide to Nutrition will get demand (reader interest, search queries, etc.) related to trends in dieting, whether we want it to or not. So it’s our job to either answer or redirect the questioning.
“X is too technical for our readers so we should omit it.”
It’s true we don’t want to make it harder to read the more accessible and popular parts of a guide.
However, ideally, we are still a path to the deeper and more technical material. We don’t want people to go to Google instead of us on a topic we’re covering.
Hiding complexities from readers goes against the assumption that they are 100% intelligent.
The solution is usually links or grouping technical content into more specific sections for more technical readers, etc.
Again, this is important so we address demand and search data. Our writing and our product very much depend on the long tail nature of the subjects we cover.
In particular, search features depend on depth.
“We shouldn’t link to X, because we want people to stay on our guide.”
No. Keeping people on the site is a concern for an impression-driven business dependent on ad revenue. Our goal and our business is helping people find what they need as effectively as possible, whether content is in a guide or elsewhere on the web or somewhere in print.
That said, we should also summarize or pull in content (if not now, over time), as that’s what’s best for readers. That’s why we put mouseover snippets on links, and will add other features like this too.
Also, we need links for external search and other features!
“We link to X and Y so we should link to everything else like this too.”
Well, no, it’s not wise to link to every tangentially or potentially related thing. A laundry list of resources can overload the reader, just like with a Google search. Including things of generally low value dilutes our own credibility, and doing so is not a fair brokering of readers’ attention.
We need to do the hard work for the reader of curating what matters, making it clear why the material we chose made the cut, while other material did not.
Readers will ultimately help us with this, suggesting new, hard-to-find material, which will also be fielded, reviewed, and included or discarded by experts and editors.
Pitfalls
A few pitfalls seem to be common when we start writing guides. Here are a few we’ve seen in our editorial work so far:
Not doing enough research up front.
We shouldn’t be writing a lot without exploring every other good resource already out there.
There may be multiple books on this topic.
Within the whole internet of content on a topic, there are bits where people have written well about it before—even if the form or scope is a little off, or it’s out of date.
For many topics, there are likely communities and experts to connect with, who can be found on Twitter, Reddit, forums, etc.
We need to research all this and have a perspective on it before finalizing the scope and table of contents, and predicting the audience.
A lot of this of this can happen throughout the writing process, too:
Again, this is a lot of work, but for pretty much every section, it’s fair to say, “Are we covering this better than every other page on the internet?”
A writer should be doing a lot of Google searches on each section, as well as deeper literature searches.
We link and cite the subset that deserves mention (for any reason at all, including that it’s notable but wrong or incomplete).
Google searches help to highlight poor content and misconceptions, too, which can improve our own coverage.
Forgetting to add links.
This is not easy, but pretty much every concept that isn’t common knowledge or needs context or citation should be linked.
Link liberally but not indiscriminately. Every link must be in service of our editorial principles.
You might have to do a dozen Google searches, ask a university librarian and two experts to be sure the resource you chose is credible and authoritative, but that’s a good thing. You just saved the reader from doing all that work.
Starting in the middle.
Concept examples:
Not explaining why a topic matters.
Not laying out fundamental principles.
Forgetting to define concepts so common they seem obvious but are in fact complex (What is capital, anyway? What is a company? What is currency? Is it the same as money?)
Defining concepts in circular ways, where A depends on A, or A depends on B and B depends on A.
Defining concepts in an order that doesn’t work from the ground up, where A depends on C but C isn’t defined. (Like talking about investors before talking about stock, or talking about blocks in the blockchain before defining the significance and nature of hashing.)
Section examples:
Skipping or not having enough information on the significance of the topic.
Ignoring entire classes of resources, like listing only online resources but no notable print books.
Not including or neglecting to sequence major events in the history of the topic; not demonstrating how it has changed over time.
Providing a roadmap or other introductory material that only speaks to the needs and concerns of one kind of reader.
Not using the right voice. We don’t want:
Marketing voice. “This is awesome and it will help you, and it contains expert tips you won’t find anywhere else.”
Know-it-all or paternalistic voice: “We’re experts and we have the answers.” “If you follow the advice we give you, you’ll be fine.”
It’ll-be-easy voice: “Once you learn these 17 tricks, it will be easy!”
A voice that has no life or caring to it. Dry or needlessly boring writing helps no one.