Brainforge Knowledge

guide-authoring-playbook

4 min read

Enablement guide authoring playbook

Purpose: Standard for writing Brainforge Enablement Guides: lightweight, moment-of-need learning artifacts that help a teammate perform one workflow correctly in real work.

Audience: L&D authors, workflow owners, and engineers adding guide content under programs/guides/.

Related: NORTH-STARS.md · guide-page-standard.md · programs/guides/README.md

Last updated: 2026-04-17

1. When to use an Enablement Guide

Use an Enablement Guide when all of the following are true:

  1. The learner needs help with one applied workflow, not a multi-module course.
  2. The desired outcome is immediate behavior change in live work.
  3. The artifact should be easy to revisit at the moment of need.
  4. The topic does not need certification, progress tracking, or a sequence of lessons.

Use a course instead when the learner must build through multiple prerequisite concepts, complete several modules, or demonstrate broader mastery over time.

2. Design rules

  1. One guide = one behavior. If a draft teaches more than one workflow, split it.
  2. Backwards design first. Start from the observable behavior, then decide what evidence and instruction are needed.
  3. Prefer Type 1 or Type 2 learning targets. Guides are best for concrete procedural work or bounded judgment. Avoid pretending a single guide can assess Type 3 disposition change.
  4. Use explicit instruction. Every guide should include an I Do, We Do, and You Do flow.
  5. Keep cognitive load low. The learner should not have to reconcile multiple systems, exceptions, and branches at once unless the workflow genuinely requires it.
  6. End with an implementation intention. Make the learner name when they will use the workflow next.

3. Folder structure

All guides live under:

knowledge/people/learning-development/programs/guides/

Each guide gets one folder and one main README.md.

programs/guides/
  README.md
  opencode-quickstart/
    README.md
  doordash-updates-overview/
    README.md

Naming rules:

  1. Folder names use lowercase kebab case.
  2. The guide body lives in README.md.
  3. Supporting screenshots or files can sit beside README.md only when necessary.

4. Required guide anatomy

Every guide README.md should include these sections in this order.

# {Guide title}
 
**Owner:** {name}
**Status:** Draft | Active | Archived
**Audience:** {who this is for}
**Time:** {time to complete or review}
**Type:** Enablement Guide
**Updated:** YYYY-MM-DD
 
---
 
## Why this guide exists
 
> **Desired behavior:**
> When the learner is in {real work context}, they can {observable action}.
 
## Before you start
 
## I Do
 
## We Do
 
## You Do
 
## Verify it worked
 
## Common failure modes
 
## Check your understanding
 
## Implementation intention
 
## Related guides and courses

5. Writing guidance for each section

Why this guide exists

  • State the real work trigger.
  • Explain what changes after the learner uses the guide.
  • Use a desired-behavior blockquote so the target is obvious.

Before you start

  • List prerequisites, permissions, and source-of-truth docs.
  • Keep this short.

I Do

  • Demonstrate the workflow clearly.
  • Use ordered steps.
  • Link to the authoritative doc or system when needed.

We Do

  • Provide a guided example or decision path.
  • Make the learner compare what they see to the demonstrated pattern.

You Do

  • Assign one real action the learner can perform now or on the next live task.
  • Do not make this a generic quiz question.

Verify it worked

  • List observable checks in the tool or artifact.
  • Include what success looks like.

Common failure modes

  • Name the most likely mistakes.
  • Give the shortest correction path.

Check your understanding

  • Use 2-4 quick prompts that require explanation or choice.
  • Prefer short-answer or decision prompts over trivia.

Implementation intention

  • End with an if-then sentence.
  • Format it as: When I next ..., I will ...
  • Link sideways to adjacent guides.
  • Link upward to a course only when the guide sits inside a broader skill path.

6. Quality bar

Before marking a guide Active, confirm:

  • The guide teaches one workflow only.
  • The desired behavior is observable in real work.
  • I Do, We Do, and You Do are all present.
  • The guide includes a verification step.
  • The guide includes an implementation intention.
  • Links point to current Brainforge sources of truth.
  • The artifact can stand alone without an accompanying meeting.

7. What not to do

  • Do not turn a guide into a mini-course with multiple lessons.
  • Do not write long background sections before the learner sees the workflow.
  • Do not use a guide as a dumping ground for every edge case.
  • Do not claim certification or mastery from guide completion.

Graph View

Backlinks