Writing a guide from scratch

Follow this process when you are writing a guide from scratch or making major updates to an existing one. The goal is to help you spend time where it matters most and avoid writing a full draft before we align on direction.

You are always welcome to draft independently. But in most cases, collaborating through this process leads to stronger guides and fewer revision rounds.

Read the contributor style guide for voice, tone, and how we phrase recommendations—it pairs with each step below.

The process

1. Choosing and scoping a guide

   A guide works best when it has one clear focus: one primary situation, risk, or goal—not a survey of everything tangentially related.

   We encourage you to reference our guide proposals list and see if any of those ideas are a fit for your skills and interests. Feel free to propose a new idea if you think it could help our audience.

   Start from a concrete reader situation. Ask who this is for, what they are trying to do (or avoid), and what goes wrong if they do nothing. You should be able to describe the guide in one concrete, clear sentence (e.g. “This guide helps you prepare for a protest”).

   Keep the promise narrow. It is better to cover one slice thoroughly than to stitch several topics into a single guide.

   Length and attention: We assume someone may only give us 15 to 30 minutes. Aim for a guide they can use in one or two sittings: enough depth to act, not enough to replace a book or a training curriculum. You can and should use sections (with risk level boxes) to break up the guide into smaller, more manageable chunks.

   Action step: Contact us with the topic you have in mind. If possible, please share examples of public writing/training where you explain complex ideas clearly.

2. Outline

   What happens: We collaborate with you on an outline—the intro and section flow—and align on scope before you write a full draft. It is much easier to adjust direction at outline stage than after a full draft is written.

   Goal of this phase: Lock the scope and structure so your drafting time is well spent.

3. Drafting and revisions

   What happens: You write a first full draft that follows guide structure and formatting (checklist items, how-to sections, and alerts where they fit). Then we run expert review and feedback rounds.

   You can send a draft in multiple formats:

   • Use our visual editor and submit a pull request. (Recommended)
   • Edit the .mdx files directly in your fork of the repository and submit a pull request. This requires creating a separate file for each checklist item, which can be tedious.
   • Write it in a Proton Doc and we’ll convert it to the correct format.

   Typical focus during revisions:

   • Consistency with our style guide and page structure and formatting docs
   • Accuracy and citations to real-world examples
   • Clarity and plain-language framing
   • Recommendation strength and trade-offs

   Goal of this phase: Get to a publish-ready draft that is clear, practical, and trustworthy.

4. Publishing

   What happens: We finalize copy, publish the guide on the site, and share it through our normal channels.

   All guides are currently published anonymously.

What helps drafts move faster

• Start with the risk and who it affects
• Make your primary recommendation obvious (rather than listing multiple options all with equal priority)
• Name trade-offs directly
• Use plain language and avoid jargon
• Keep language plain and actionable
• Flag any areas where you want extra editor feedback
• Keep the guide focused and to the point