All About Best Practices

• Your reader can be someone with basic literacy and general life experience, but no specialized technical or academic knowledge
• Assume your reader cares about community work but may not have professional training in technology, organizing, or project management
• Avoid jargon, and when technical terms are necessary, explain them immediately

How to achieve this:

• Replace technical terms with everyday equivalents whenever possible
• When technical terms cannot be avoided, define them using comparisons to familiar situations
• Test your writing by asking: "Would my neighbor understand this?"

Example:

"When we talk about technical decisions, we are talking about decisions of how to build something. Say how to build a house for example, you could build a house from expensive rare materials that look amazing but need special experts to repair. Or you could build a house from common materials that any local builder knows how to fix."

Not like this:

"Technical decisions involve architectural choices regarding technology stack, dependency management, and maintainability considerations that impact long-term project sustainability."

• Complex ideas become clear when compared to familiar situations
• Every major concept should have at least one concrete comparison to daily life
• Comparisons should be genuinely parallel, not just decorative

How to achieve this:

• For each abstract concept, brainstorm 3-4 everyday situations that work the same way
• Choose comparisons from universal experiences: houses, bicycles, cooking, family life, neighborhood activities
• Develop the comparison fully—don't just mention it and move on
• Use the structure: "Think about [familiar thing]. [Develop the comparison]. [Connect back to the main topic]."

Example:

"Think of it like water for your home. Most of us depend on the city water system. Water flows from the pipes whenever we turn on the tap. This works great most of the time. But people who live in places where the water sometimes stops flowing often keep large containers of water stored just in case. They have a backup plan. Community technology platforms need backup plans too."

• Start with concrete situations and stories
• Extract principles from the stories
• Ground abstract advice in specific scenarios

Article structure pattern:

1. Opening story (2-3 paragraphs): Two contrasting scenarios showing different outcomes
2. What made the difference (1 paragraph): Transition from story to analysis
3. Explaining the concept (2-3 paragraphs): Define what we're talking about using comparisons
4. Decision sections (major sections): Each explores one aspect through explanation, comparisons, and examples
5. Synthesis (final section): Connect all principles back to the overarching goal

Example:

The article opens with two neighborhood groups building government transparency platforms. One succeeds, one fails. Only after establishing these concrete outcomes does it explain "technical decisions" as a concept.

• Assume readers are intelligent people doing their best
• Never talk down or use condescending language
• Acknowledge difficulty and complexity rather than pretending things are simple
• Be honest about unknowns and limitations

How to achieve this:

• Avoid phrases like "you just need to" or "simply do X" when things are actually complex
• Acknowledge tradeoffs and difficult choices
• Recognize that people have constraints you may not know about
• When describing mistakes or poor practices, focus on why they happen naturally rather than blaming people for making them

Example:

"Volunteers often want to use the fanciest newest tools because those tools are exciting and make them feel like expert builders or enable them to practice new skills. But fancy new tools create problems for community projects."

Not like this:

"Using the latest frameworks is a common beginner mistake that shows inexperience with real-world constraints."

• Write in flowing prose with clear paragraphs
• Use headers only for major section breaks
• Avoid bullet points, numbered lists, bold emphasis, or other heavy formatting
• Let ideas flow naturally rather than chunking everything into lists

How to achieve this:

• When you have multiple related points, write them as sentences in a paragraph: "Good documentation includes several elements. First, a simple explanation of what the platform does... Second, a description of how information flows... Third, step-by-step guides..."
• Use line breaks between paragraphs to create visual rhythm
• Headers should mark major topic transitions, not subdivide every few paragraphs
• The only exception: when documenting a specific structure or process where enumeration is essential

Example:

Notice how the "What good documentation includes" section lists six elements but writes them as flowing paragraphs, not bullet points. Each element gets developed in a full paragraph.

When lists are good:

• Documenting specific steps in a process
• Providing checklists or reference material that readers will return to repeatedly
• The article itself is a tutorial or guide (different genre than analysis articles)

One sentence defining what the practice/pattern is - Clear definition of the subject

1. One sentence explaining the core problem it addresses - Why this matters
2. 2-3 sentences describing the key principles or approach - What makes this work
3. One sentence acknowledging tradeoffs or limitations - What this approach gives up or doesn't do well
4. One sentence connecting to long-term community goals - The deeper why

Example abstract:

"Community co-working sessions create sustained engagement through regular, low-pressure gatherings where participants work on their own projects while benefiting from shared space, peer support, and collective momentum. [Definition]

This pattern, refined over seven years in blockchain developer communities, prioritizes doing over discussing, building relationships through working side-by-side, and maintaining consistency over pursuing growth. [Context and key principles]

Good co-working sessions focus on creating conditions where real work happens, connections form naturally, and participants leave with tangible progress. The key is starting small with people already doing projects, meeting regularly in comfortable spaces, structuring time to balance focused work with social connection, and keeping the barrier to entry low. [More principles]

Although this approach may seem less impressive than large events or structured workshops, it builds the sustained relationships and consistent progress that keep community initiatives alive over years." [Tradeoff and connection to larger goal]

Purpose: Show two different outcomes from similar starting conditions

Structure:

• 2 paragraphs describing first scenario (the one that failed or had problems)
• 2 paragraphs describing second scenario (the one that succeeded)
• 1 paragraph identifying what made the difference

Writing tips:

• Make the scenarios concrete and specific
• Both scenarios should have good intentions and capable people
• The difference should be in the practices/decisions, not in the people's abilities
• End with a transition sentence like: "What made the difference? Both groups had good intentions and skilled volunteers. The difference was in [the decisions/practices] they made."

How many sections: Typically 6-10 major sections

Each section should:

• Start with a clear header describing the decision or practice area
• Open with a concrete comparison (2-3 paragraphs)
• Explain the underlying principle (1-2 paragraphs)
• Provide practical guidance (3-5 paragraphs)
• Include specific examples (integrated throughout, not separated)

Section formula:

1. Comparison - "Think about [familiar thing]..." Develop this for 2-3 paragraphs
2. Connection - "Community projects face similar..." Transition from comparison to the topic
3. Explanation - Explain the principle in clear language
4. Guidance - Offer specific approaches, considerations, or practices
5. Examples - Weave in concrete examples throughout (not as separate "Example:" callouts)
6. Closing - One sentence emphasizing what matters most about this decision

Purpose: Tie all the decisions/practices back to the overarching principle

Structure:

• Restate the core principle (1 paragraph)
• List the key decisions as a summary (1 paragraph, written in prose not bullets)
• Acknowledge limitations (1 paragraph)
• Final paragraph connecting to community values and long-term goals

Closing formula:

"All these decisions about [topic] come down to one principle: [restate core insight]. This is different from [contrast with common but less effective approach]."

If the article draws from documented practices elsewhere, include:

This article documents patterns from [source community] tested over [time period]. The applicability to [other contexts] is still being established. We invite practitioners to test these patterns in their communities and share their experiences—both successes and failures—to help us all learn what works under different conditions.

Problem: Trying to give all the nuance and caveats before the reader understands the basic idea

Solution:

• State the simple principle first
• Give concrete examples
• Then add nuance and exceptions
• Remember readers can handle "this is generally true, but..." better than "this is true except when X, Y, Z, unless A, however if B..."

Problem: Writing like you're submitting to an academic journal or professional publication

Warning signs:

• Words like "utilize" instead of "use"
• Phrases like "in order to" instead of "to"
• Passive constructions: "it was discovered that" instead of "we found"
• Abstract nouns: "the implementation of" instead of "implementing"
• References to literature without explanation

Solution: Imagine you're explaining this to a casual friend over coffee. Write how you would speak.

Problem: Jumping straight to the principle without grounding it in familiar experience

Example of the problem:

"By experience in CASE-001. Documentation should be written for newcomers. It should explain concepts clearly and provide step-by-step guidance."

Better:

"Imagine you move into a new house. In the basement, you find a complicated machine with dozens of buttons and displays. There is no instruction manual... [develop this comparison for 2-3 paragraphs]... In the story of [project](url) we can see that documentation is the instruction manual for your community platform."

Problem: Stating rules without explaining why they matter or when they apply, making other readers use it in wrong timing for a wrong reason

Example of the problem:

"Always use common programming languages. Never use microservices architecture. Keep documentation updated."

Better:

"Older, boring, common tools are usually better choices for community platforms. Think of it this way: would you rather build your house using construction methods that every builder in your town understands, or using experimental methods that only a few specialists know about?"

Problem: So many qualifiers that no clear guidance emerges

Example of the problem:

"You might want to consider perhaps trying to think about potentially meeting more regularly, though this may not work for everyone and depends on various factors."

Better:

"Meeting every week or every two weeks works better than monthly because the sessions become a habit rather than an occasional event. Choose based on when your core participants can reliably attend."