Writing Comprehensive Practical Guides

July 10, 2026 · View on GitHub

Version: v0.1 (last update 2026-06-09)
Joshua Levy (github.com/jlevy)

Guidelines for one specific genre of practical prose: the comprehensive practical guide—a reference work that helps readers navigate a complex topic, built for recurring use by multiple kinds of readers. This is not guidance for every practical document. Use it when writing a guide; use practical-prose-guidelines.md for practical prose generally, and common-doc-guidelines.md for all documentation.

These guidelines extend practical-prose-guidelines.md the way that document extends common-doc-guidelines.md: everything there still applies; this adds what the guide genre demands. They distill years of editorial practice developing long-form guides (at Holloway and before), refined in conversations with editors, writers, and expert reviewers.

These guidelines are deliberately opinionated, and several push writers and editors in directions they don’t typically go. Not all practical writing is of this type. Each guideline below opens with an applies when note; when the condition does not hold, the guideline does not apply, and following it anyway can make a document worse.

What Makes a Guide?

A guide has a single purpose: to help the reader navigate complexities. It aims to be the best single place to start or return to on the topic it covers.

Guide content differs from other nonfiction in several ways:

Practical orientation: it offers helpful guidance, and gives the reader 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.
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, not a blog post you forget after a day. It continues to be of use to a single person over time as they encounter different problems and questions.
Built to improve: on complex topics subject to change, no guide is ever perfect; it must be built to improve over time, not published as the fixed work of a single author.

A guide is not: historical or narrative nonfiction; writing devoted to a single thesis; writing primarily for entertainment; or celebrity-oriented writing that is mostly of interest because of who is writing.

Also, while a guide may share facts and details with a Wikipedia article, it should not imitate Wikipedia’s policies. Wikipedia is restricted to consensus facts, bars original research, including a writer’s own analysis or firsthand expertise, and rejects how-to guidance and Q&A-style material. All of these can be appropriate in a practical guide. In fact, it is this kind of expert judgment that makes a guide more valuable than a Wikipedia article.

When These Guidelines Apply

Use this document only when the intended artifact is a comprehensive practical guide. The guide genre presumes four conditions, and each guideline below leans on one or more of them:

Discretionary readership: the reader can leave at any time.
Situational variability: the right action depends on the reader’s situation; there is often no single correct answer.
Mixed and multi-sided audiences: readers vary in expertise and may sit on different sides of the topic.
Long shelf life: the work is meant for recurring use and ongoing improvement.

A runbook, a spec, or an internal memo typically fails several of these conditions—and several guidelines below would harm those documents. Check the applies-when note before applying any of them.

The Guidelines

1. Make Deep Coverage Accessible

Applies when: the audience spans beginner to expert (condition 3). Does not apply when: the audience is uniform (a spec for one team).

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. A guide aspires to be both deep and engaging—technical and accessible. Both big ideas and technical details are essential: ideally, a guide weaves details together through foundational concepts and broader ideas. Can both novice and expert learn (different) things quickly?

Specific strategies:

Start with zero assumptions about what a reader knows, so anyone can start reading easily and skip ahead if it’s too basic.
Combine fundamental concepts and brief overviews with deeper technical detail. 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, such as 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. What kind of diagram would impress both a beginner and an expert?
Emphasize confusions, overlooked suggestions, pitfalls, and misunderstandings that are common.
Use technical terminology whenever appropriate, but always define the terms clearly.
Give helpful or illuminating historical background that many may not be aware of.

2. Earn the Respect of Experts First

Applies when: the work is a public reference whose authority matters (conditions 1 and 4). Does not apply when: the readership is known and credibility is established (internal docs).

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. Accuracy, precision, and clarity in their estimation is the first goal; accessibility comes next, but never when it compromises credibility among experts.

Two things make writing credible to experts:

Technical vigilance: be accurate, precise, logical, and clear—and explicit when there is uncertainty or controversy. On this there is no compromise.
Stylistic clarity: experts are remarkably sensitive to secondary signals—not focusing on details, overlooking exceptions, not conveying context, over-marketing, or over-generalizing.

It’s easy to slip into marketing-speak ("our amazing guide unlocks secrets!") or gloss over confusing nuances ("just remember these five tricks!"). Be ambitious enough to aim for comprehensibility and credibility, but stay humble: if the topic is complex enough to deserve a guide, the guide is imperfect and improving.

3. Start From the Beginning

Applies when: readers arrive with widely varying foundations (condition 3). Does not apply when: shared context is guaranteed (a team runbook can start in the middle—that is what its context section is for).

A common mistake for a knowledgeable writer is to “start in the middle”: writing at the level they’re most comfortable with, without relating that knowledge to the topic’s foundations or broader context. It’s easiest to write for someone with similar expertise to yourself—the curse of knowledge.

So when outlining and writing a reference work, start from the beginning: foundations, background, readers’ motivations, and the significance of the subject, working toward more advanced ideas with details inserted liberally. Watch for the definition failures that signal middle-starting:

Concepts so common they seem obvious but are in fact complex, left undefined. (What is capital, anyway? What is a company? Is currency the same as money?)
Circular definitions, where A depends on B and B depends on A.
Definitions out of order, where A depends on C but C isn’t defined—like talking about investors before stock, or blockchain blocks before hashing.

(Starting in the middle is fine when assembling your own notes—just backfill the foundations during groundwork and outlining.)

4. Imagine Readers That Are “100% Intelligent and 100% Ignorant”

Applies when: always within the guide genre; this is its central heuristic. Does not apply when: the genre itself doesn’t (expert-to-expert documents may assume shared knowledge).

Imagine your readers start out 100% intelligent and 100% ignorant. In reality most people already know something, but the assumption has important advantages:

It reminds you to start from the beginning without assuming too much knowledge.
People with varied knowledge can start early and skim forward, filling gaps; beginners can see everything they don’t yet know.
It avoids “writing down” to beginners—condescension, or over-simplifying important details out of fear they will confuse a novice.

Embrace essential complexity. Details matter. As Einstein possibly said, “Everything should be made as simple as possible but no simpler.” It’s tempting to hide messy or confusing details from readers, but do not underestimate people’s ability to manage information when it is supplied well.

If you respect the reader, the reader will respect you. The ability to learn has little to do with past exposure to a topic. Writing with clarity and intelligence makes readers feel capable; if they have to push themselves a little to keep up, that’s often just fine, particularly for important and complex material.

5. Cover the Facts That Are Helpful

Applies when: curating scope for any guide (condition 2). Does not apply when: the document type fixes the content (a reference table).

The priority is to be helpful, not only factual. Guides cover many facts, and may include foundational sections devoted to facts—but the ultimate goal is to serve the reader helpfully, and that determines which facts are relevant. This means prioritizing helpfulness over pure neutrality: a strict Wikipedia-style point of view omits genuinely helpful material that does not fit the bar of consensus facts. Alongside the facts, include informed opinions, advice, context, and rationale. Actionable knowledge rests on factual knowledge: cover the foundations and context that will support future learning. Having a firm grasp of the mathematics of compound interest is not essential for every investment decision, but it helps in so many situations that learning it early pays off.

6. Give Frameworks, Not Answers

Applies when: guidance is advisory and the right action is situational (condition 2). Does not apply when: the correct action is determinate—procedures, runbooks, compliance steps. There, prescribe plainly; a framework where an instruction belongs is evasion.

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 whether your new company should be a C Corp or an LLC, or ask a doctor friend if you need back surgery, the expert will not just give you an answer. On complex and important decisions, experts turn around and ask you the right questions, to understand the real elements of the problem—then help you decide what’s right for your situation.

The most helpful guidance on important decisions is neither too assertive (fully prescriptive, just telling you what to do) nor too passive (waiting for you to make decisions you’re not informed enough to make well). 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.

(Contrast search engines and AI assistants, which aim to give answers. “Capital of Poland” has one; “Should my business be an LLC?” does not.)

7. Cover Controversy

Applies when: informed opinion genuinely varies on material questions. Does not apply when: apparent “controversy” is consensus plus misconception—then state the consensus and dispel the misconception.

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:

Key points on different sides of an issue, with key citations.
If there is broad agreement on some parts, give recommendations on those parts.
Include the facts and frameworks the reader needs to make informed decisions. Often, experts can agree on a clearly articulated framework for making a decision even when they don’t agree on a single recommendation.

8. Help People See What They Don’t Know

Applies when: readers cannot yet name what they’re missing (conditions 2 and 3). Does not apply when: the reader’s question is fully formed and specific.

One of the most helpful things you can share is a sense for what someone doesn’t know—indeed, what they didn’t even know to look for. 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 show readers quickly what they are unfamiliar with and what they can hope to learn. This is the beginning of fluency—and one reason great books are so helpful: an author has spent years deciding what to cover.

Concrete forms: a table of contents with a surprising but helpful section; an infographic that goes broader and deeper than most online visuals so even an expert learns something; inclusion of dangers and pitfalls, not just facts and recommendations; listing and dispelling common misconceptions.

9. Link or Cite Pretty Much Everything

Applies when: publishing for the open web with discretionary readers (condition 1). Does not apply when: the document must be self-contained (printed matter, sealed specs)—there, inline the essentials.

It’s easy to write without adding links, but far more helpful to do the work of finding the links that will help the reader. Readers often don’t know they want more information; a well-chosen link lets them discover something unexpected and helpful. Linking also gives credit where it’s due.

Three kinds of links, in descending order of prominence:

Recommended links: resources that are useful, widely known, or well-regarded, called out in the text with context—who wrote or produced the resource and why it’s important. Famous books, definitive posts, and helpful tools.
Elaborative links: more detail or context on something mentioned in passing—for example, Wikipedia articles on key concepts. These need no context beyond the inline link itself.
Pure citation links: verifying a fact or sourcing a statement, in parentheses after the information being verified.

Working rules: for each paragraph, ask what the best links giving detail on it are; for each link, ask whether there is a better one; prefer multiple citations when each adds value—you are saving the reader several searches. But link liberally, not indiscriminately: a laundry list of resources overloads the reader, and including things of low value dilutes credibility. Curate what matters and make it clear why what you chose made the cut.

10. Broker Attention Helpfully

Applies when: always—this is the economic statement of the Lucid principle.

The job of a guide is to earn the trust of readers by brokering attention helpfully: helping readers allocate their time in the ways that are most effective. Obtrusive ads, clickbait, and popups broker attention in ways that are not helpful; readers notice over time and judge the value of media by whether it feels valuable.

Consequences for writers:

The volume of words on a subject should roughly reflect its likely importance to readers.
Topics covered should reflect demand—the information the audience really wants.
Topics that are very important, even to a small group, should not be omitted.
Including context and information from many sources saves the reader that research.
Sometimes readers ask for one thing but need another: readers searching for a fad diet could benefit from nutrition fundamentals, so cover and connect both.
Pitfalls and misperceptions are just as important as straightforward facts.

Applies when: several kinds of readers—sometimes on opposing sides—share the topic (condition 3). Does not apply when: the document has one reader or one role (most memos).

Know your audience, but don’t narrow your audience. A shared resource can be of extraordinary benefit to multiple, related audiences who normally find themselves on different—sometimes opposing—sides: a guide to equity compensation written for employers and employees, a guide to venture capital for investors and entrepreneurs.

Why this works:

It helps readers navigate where information asymmetry has made it difficult for people to communicate, relate, and empathize with the other side’s motivations.
It forces deeper discussion during writing: covering compensation with both employers and employees in mind drives the work to cover differences of opinion and express complexities more clearly for everyone.
It is valuable for both sides to know they’re operating with the same information—one side can even refer the other to it.

12. Intrigue Right Away

Applies when: readership is discretionary (condition 1). Does not apply when: readers are captive (a required spec review)—there, lead with the decision, not a hook.

Help people appreciate a guide’s value right away: if you don’t capture attention quickly, you might not get it at all. The 30-second rule: does the work make people, no matter their experience level, lean in right away? Skimming top to bottom or through the table of contents, is there enough detail, clarity, and logical structure that most people say “Oh, interesting”? A beginner should be impressed with the depth but not too intimidated to start; an expert should find details that earn their respect; readers of many types should find “nuggets.”

This is not clickbait ("5 easy steps to your first million!") and not provocation or entertainment. The aim is to organize the work to give visitors a clear sense of what’s on offer, so they know that if they keep reading, they will learn something of value.

Groundwork

The numbered guidelines above describe what a finished guide should do. Groundwork is the open-ended research process that comes before outlining and recurs before each major revision. It is guide-writing process, not part of the all-purpose Practical Prose rubric, and it matters most when the topic spans multiple roles, experience levels, regions, institutions, or incentives.

The output is a groundwork note: a working document that states scope, audiences, entry scenarios, significance, key questions, terminology, sources, confusion points, controversies, and open decisions for the outline. It should be concise enough to use while outlining but detailed enough that an editor or agent can audit the resulting guide against it.

Scope the Intended Guide

Before gathering more material, answer: What will the guide cover? What will it not cover? What might be deferred to a later release? And why is a comprehensive guide the right form, rather than a runbook, article, FAQ, reference table, or decision memo?

Map Entry Scenarios

List the reasons a reader might arrive: the 5-10 most common situations, the decision or risk or confusion behind each, and which belong to beginners versus experienced readers returning with a specific problem. Include misguided reasons, because misguided entry scenarios show which misconceptions the guide must redirect.

For a guide to equity compensation, entry scenarios include “quitting my job and need to decide whether to exercise stock options” and “got a job offer and need to know what I can negotiate around equity.” For a guide to nutrition, a misguided entry scenario might be “want to lose five pounds a day.”

Define Audiences and Boundaries

Comprehensive guides often serve multiple, related audiences; name them deliberately, then name who is outside the guide’s scope.

Are there multiple audiences who can share one reference?
Are any audiences on different sides of the same topic, such as employers and employees, buyers and sellers, investors and entrepreneurs?
Are there groups the guide should exclude because of jurisdiction, industry, role, language, or maturity?
Are there different stages of learner, such as students, first-time practitioners, and experienced professionals?
What would each audience gain from understanding the others’ constraints?

Establish Significance

A serious guide should be able to explain why the topic is worth the reader’s time. Write short notes for the categories that matter; not every guide needs every category.

Individual: concrete effects on readers’ money, health, time, relationships, safety, work, or opportunity.
Professional and academic: roles and institutions where the topic is necessary, and how formal treatment differs from practical use.
Decision-making value: decisions the guide helps make, costly mistakes it helps prevent, opportunity costs it helps readers see.
Emotional and public-discourse: where the topic comes up in daily life and news, what emotions shape it, and whether it is marketed, politicized, or moralized.
Timeliness and history: why now matters, what changed recently, how expert and popular views have shifted.
Global: how the topic changes across language, culture, geography, law, or market structure.
Authorities and commerce: the people, institutions, standards bodies, companies, and incentives a reader should know about.
Community: who has historically had access to the knowledge, who has been excluded, and who is harmed by common misunderstandings.
Author: why the author or team is interested, and what access or experience they bring.

Gather Questions and Terminology

Collect questions before finalizing the outline, from search, forums, interviews, expert conversations, existing books, support queues, and reader feedback: the 5-20 most fundamental questions someone would ask with no prior context, the 20-200 most common questions, which questions belong to which entry scenarios, which are missing because readers don’t yet know enough to ask them, and which are really requests for a framework rather than a simple answer.

In parallel, assemble the terminology map: the key terms, concepts, figures, institutions, and standards. For each important term, define it from first principles, note terms often confused with it, identify circular or out-of-order definitions the guide must avoid, and mark where the guide should first define it.

Audit Change, Confusion, and Controversy

Ask the author, potential readers, and experts: What are the most confusing areas for typical readers, and the most frustrating for practitioners? What is changing fastest? What useful point do experts know that most readers do not? What are the two or three things everyone should understand? Where do respected experts disagree, where is apparent controversy really consensus plus public misconception, and what historical context explains the disagreement?

Consult Across Experience and Expertise

The most important process rule: consult across diverse experience and expertise before the outline hardens, and again before publication.

Diversity of practical experience: talk with people who touch the topic from different roles, institutions, company sizes, geographies, or communities. Lawyers, investors, and founders will see different parts of equity compensation; managers and individual contributors will surface different parts of hiring or workplace guidance.
Diversity of expertise: talk with beginners as well as experts. Beginners reveal what the guide must explain from first principles; experts reveal what the guide must get exactly right.
Diversity within roles: do not treat one expert, one company, or one community as the whole topic. People with the same title in different organizations can face different constraints.
Questions and misconceptions: ask what the current outline misses, which common questions are misguided, which terms are confused, and where controversy or practice is changing.

The groundwork is ready when an editor can answer: Why does this topic deserve a comprehensive guide? Who is it for, and who is it not for? What reader situations does it serve, what foundations must appear early, what controversies and technical depths must not be skipped, and which sources and reviewers are necessary for credibility?

Voice

A guide’s voice should combine three qualities. It helps to imagine an expert and trusted friend sitting with you over coffee: years of experience, but the emotional intelligence to remember what it is like to know much less.

Rigor: Accurate, precise, logical. Expert review and cited sources. No dumbing down, no hot takes.
Clarity: Direct and concise. Respect the reader’s intelligence. As simple as possible, but preserve the real complexities of the topic. Many readers want to move up rapidly on Tim Urban’s scale for understanding complex ideas, often from a 2 or 3 to a 7, 8, or 9; write to help them do that as directly as possible.
Warmth: Genuine; friendliness over stiffness; empathy while preserving clarity. Gentle humor is welcome; avoid jokes that are mean-spirited, offensive, or misleading.

Four voices to avoid (they fail readers in different ways, and all of them fail the respect test of guideline 4):

Marketing voice: “This is awesome and contains expert tips you won’t find anywhere else.”
Know-it-all or paternalistic voice: “We’re experts and we have the answers. Follow our advice and you’ll be fine.”
It’ll-be-easy voice: “Once you learn these 17 tricks, it will be easy!”
Lifeless voice: writing with no life or caring to it. Dry or needlessly boring writing helps no one.

(The first three are register failures scored under E1 Clarity; the fourth is the Tone / Reader Respect check. See practical-prose-guidelines.md.)

Answering Common Objections

Conceptions from other kinds of writing often do not apply to guides. The objections below come up repeatedly in editorial work; the responses are the working answers.

“We shouldn’t cover X because it’s controversial / too subjective.” Cover it—in a way that promotes understanding. Give the 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? Has opinion changed over time, and is it likely to change again? If you dig deep enough into the reasons for disagreement, you can often find a framework that reconciles them.
“We shouldn’t cover X because it’s just a fact you can look up.” Cover the facts that are relevant; it’s the analysis and processing of those facts that leads to useful insight. Cover necessary facts in depth and reference tangential details with brief mentions and links.
“We shouldn’t cover X because it’s outside our scope.” For any such topic, the choices are (1) mention 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 in the guide, address it—possibly by redirecting to the right framework or line of questioning.
“X is too technical for our readers, so we should omit it.” Hiding complexity contradicts the assumption that readers are 100% intelligent. The solution is structure: group technical content into clearly marked sections, or link to deeper material—remain the path to the deep material rather than sending readers elsewhere.
“We shouldn’t link out, because we want people to stay.” Keeping people on a site is a concern for an impression-driven business. A guide’s job is helping people find what they need as effectively as possible, wherever it lives.
“We link to X and Y, so we should link to everything like them.” No—curate. A laundry list of resources overloads the reader and dilutes credibility (see guideline 9).

Callouts

Guides benefit from a consistent vocabulary of callouts for content that should stand out from running prose. A few possible semantic categories (render them with whatever admonition mechanism the medium provides):

Category	Use for
Important	An important and often overlooked tip
Danger	A serious warning, where risks or costs are significant
Caution	A limitation, disadvantage, or quirk
Controversy	A topic where informed opinion varies significantly
Confusion	A common confusion or misunderstanding, such as confusing terminology
Technical	A technical point (arcane or academic, not essential)
Scientific	An academic or scientific detail or reference
New	New or recent developments
Incomplete	Expansion or improvement needed
Story	A personal anecdote or story
Example	An example or illustration
Resources	Further reading or a list of resources

The last three mark content types rather than warnings, but belong in the same consistent callout vocabulary.

practical-prose-guidelines.md: the 20 dimensions all practical prose follows; this document extends them for the guide genre.
practical-prose-principles.md: the seven principles; “broker attention helpfully” (guideline 10) descends from Lucid.
practical-prose-bibliography.md: sources, including the Holloway editorial-guidance lineage of this document.