# Documentation Best Practices (/docs/v0-1/story-portal/notebook/documentation-best-practices)

## Overview [#overview]

Effective documentation makes your Living Stories easier to maintain, collaborate on, and understand. The Story Portal provides two documentation tools—the Notebook and Story Notes—each suited for different purposes.

## Choosing the Right Tool [#choosing-the-right-tool]

### Notebook vs Story Notes [#notebook-vs-story-notes]

Understanding when to use each tool ensures better organization:

| Aspect | Notebook | Story Notes |
|--------|----------|-------------|
| **Location** | Sidebar panel | Canvas overlay |
| **Content Length** | Long-form documentation | Brief annotations |
| **Formatting** | Rich text with headings | Plain text only |
| **Position** | Not position-specific | Positioned near elements |
| **Persistence** | Permanent documentation | Often temporary |
| **Collaboration** | Shared single document | Individual notes per author |
| **Best For** | Planning, specifications | Reminders, quick feedback |

### When to Use the Notebook [#when-to-use-the-notebook]

**Use the Notebook for**:

**Planning and Structure**:
- Overall story outline
- Character development notes
- Narrative arc planning
- Major plot points

**Technical Documentation**:
- Variable naming and usage
- Complex conditional logic
- Interaction configurations
- Integration specifications

**Decision Records**:
- Why certain approaches were chosen
- Design rationale
- Alternative approaches considered
- Constraints and requirements

**Reference Information**:
- Character details
- Setting descriptions
- Style guidelines
- Asset lists

### When to Use Story Notes [#when-to-use-story-notes]

**Use Story Notes for**:

**Visual Reminders**:
- "Add audio here"
- "Check this connection"
- "Placeholder - needs final content"

**Positional Feedback**:
- Comments about specific scenes
- Notes about particular interactions
- Location-specific issues

**Temporary Markers**:
- Work in progress indicators
- Testing reminders
- Review comments
- Task markers

**Team Communication**:
- Questions about specific elements
- Feedback on particular scenes
- Handoff information
- Bug reports

## Notebook Best Practices [#notebook-best-practices]

### Structure and Organization [#structure-and-organization]

#### Use Consistent Headings [#use-consistent-headings]

Create a standard structure for all your stories:

```markdown
# Story Overview
Brief description, target audience, key goals

# Planning
Outline, character notes, narrative structure

# Technical Specifications
Variables, conditional logic, technical notes

# Implementation Notes
Scene-by-scene details, interaction configurations

# Assets Required
Audio, images, external content needed

# Testing Notes
Test cases, known issues, QA feedback

# Change Log
Major updates, version history, decisions
```

#### Hierarchical Information [#hierarchical-information]

Use heading levels to show relationships:

```markdown
# Characters

## Protagonist: Alex Chen
**Age**: 32
**Background**: Architect from San Francisco
**Goal**: Find missing sister

## Supporting Characters

### Maya Patel
Friend and colleague, provides technical expertise

### Detective Rodriguez
Police contact, provides leads
```

### Content Guidelines [#content-guidelines]

#### Document Decisions, Not Just Facts [#document-decisions-not-just-facts]

**Less useful**:
```
Scene 5 has three branches
```

**More useful**:
```
# Scene 5: Decision Point

**Design**: Three branches instead of two
**Rationale**: Testing showed players wanted more agency here
**Implementation**: Variable playerChoice tracks selection
**Alternatives Considered**: Binary choice felt too limiting
```

#### Include Context [#include-context]

**Without context**:
```
relationshipScore must be > 50
```

**With context**:
```
# Ending Requirements

**relationshipScore > 50** unlocks the "happy ending"

This threshold was set after playtesting showed 50 represents
meaningful relationship development. Lower scores felt too easy,
higher scores too difficult for most players to achieve.
```

#### Use Examples [#use-examples]

**Abstract**:
```
Variables control scene access
```

**Concrete**:
```
# Scene Access Control

## Example: Secret Path
- **Variable**: `foundClue` (boolean)
- **Scene**: "Hidden Room" (Scene 12)
- **Logic**: Scene 12 only accessible if `foundClue === true`
- **Set by**: Interaction in Scene 7 "Search the Office"
```

### Maintenance [#maintenance]

#### Keep Documentation Current [#keep-documentation-current]

**Update when**:
- Adding or removing scenes
- Changing story structure
- Modifying variables or logic
- Making significant design changes
- Completing testing feedback

**Update pattern**:
1. Make change to story
2. Immediately open Notebook
3. Update relevant section
4. Add entry to Change Log
5. Update Last Modified date in notes

#### Archive Old Information [#archive-old-information]

Don't delete—archive at bottom:

```markdown
# Active Documentation
(current information)

---

# Archive

## Original Structure (Deprecated Nov 2024)
Initial design had 5 acts instead of 3. Changed because...
```

#### Regular Review [#regular-review]

**Weekly**: Review open tasks and testing notes
**Monthly**: Update planning and technical sections
**Per Milestone**: Archive completed sections, add change log entry

## Story Notes Best Practices [#story-notes-best-practices]

### Writing Effective Notes [#writing-effective-notes]

#### Be Concise and Clear [#be-concise-and-clear]

**Good examples**:
- "Audio pending from Maria"
- "Test this path on mobile"
- "Needs final copy from client"
- "BUG: Wrong scene connection"

**Too verbose**:
- "We need to remember to add the audio file here once Maria sends it over, probably by end of week"

#### Use Consistent Prefixes [#use-consistent-prefixes]

Create a system for note types:

```
TODO: [action needed]
BUG: [what's broken]
WAIT: [blocking issue]
ASK: [question]
CHECK: [needs verification]
DONE: [completed, can delete]
```

**Examples**:
- "TODO: Add background music"
- "BUG: Connection broken to Scene 8"
- "WAIT: Client approval on content"
- "ASK: Should this scene be optional?"
- "CHECK: Test interaction on iOS"

### Note Placement Strategy [#note-placement-strategy]

#### Position Near Relevant Elements [#position-near-relevant-elements]

**Good placement**:
- Next to the scene being annotated
- Near the connection that needs attention
- Grouped with related notes
- In clear canvas space

**Poor placement**:
- Covering important elements
- Far from what they reference
- Blocking connections
- Overlapping other notes

#### Create Visual Zones [#create-visual-zones]

Organize notes by type through position:

```
┌─────────────────────────────┐
│                             │
│  [BUG notes]    [Story]     │
│  on left        [Canvas]    │
│                 [Center]    │
│                             │
│  [TODO notes]               │
│  on bottom                  │
└─────────────────────────────┘
```

### Note Lifecycle Management [#note-lifecycle-management]

#### Create → Update → Delete [#create--update--delete]

**Creation**:
- Create when issue/question arises
- Make note specific and actionable
- Position near relevant element
- Include your name context if needed

**Updates**:
- Edit note as situation evolves
- Mark progress: "WAIT → CHECK → DONE"
- Keep team informed of changes
- Update rather than create duplicate notes

**Deletion**:
- Delete when issue resolved
- Archive important info to Notebook first
- Inform team if note was collaborative
- Keep canvas clean of old notes

#### Don't Let Notes Accumulate [#dont-let-notes-accumulate]

**Weekly cleanup**:
1. Review all visible notes
2. Delete resolved items
3. Update in-progress items
4. Move permanent info to Notebook
5. Hide notes to declutter canvas

## Collaboration Documentation [#collaboration-documentation]

### Shared Notebook Guidelines [#shared-notebook-guidelines]

Since the Notebook is shared with all collaborators:

#### Use Sections for Different Roles [#use-sections-for-different-roles]

```markdown
# Content Team Notes
Story outline, character development, dialogue

# Design Team Notes
Visual requirements, interaction design, UX notes

# Technical Team Notes
Implementation details, variable usage, logic

# Shared Decisions
Approved by all teams, do not modify without discussion
```

#### Communicate Before Major Changes [#communicate-before-major-changes]

**Before restructuring Notebook**:
1. Mention in team communication
2. Consider timing (don't edit during others' work time)
3. Archive deleted content in case it's needed
4. Add change log entry explaining updates

#### Indicate Work in Progress [#indicate-work-in-progress]

Mark sections actively being edited:

```markdown
# Scene 7 - [Juan working on this - Dec 4]
(content being updated)
```

### Multi-Author Story Notes [#multi-author-story-notes]

Story Notes show author names, enabling collaborative feedback:

#### Team Review Pattern [#team-review-pattern]

**Reviewer** (creates notes):
- Add notes during review
- Be specific and constructive
- Position near issues
- Use consistent prefixes

**Creator** (addresses notes):
- Address each note
- Reply in separate note if needed
- Delete note when resolved
- Ask questions if note unclear

**Example**:
```
Reviewer creates: "CHECK: Is this choice too obvious?"
Creator creates nearby: "Made it more subtle, please re-review"
Reviewer deletes both if satisfied
```

#### Handoff Documentation [#handoff-documentation]

When passing work between team members:

**Outgoing** (creates notes):
- "HANDOFF: Audio needed for this scene"
- "WAIT: Pending client feedback on content"
- "TODO: Test this branch after API update"

**Incoming** (uses notes):
- Reviews all notes
- Addresses each item
- Deletes note when complete
- Creates new notes for issues found

## Documentation Content [#documentation-content]

### What to Document [#what-to-document]

#### Always Document [#always-document]

**Design Decisions**:
- Why this structure was chosen
- What alternatives were considered
- What constraints influenced the decision

**Complex Logic**:
- How conditional logic works
- What variables control behavior
- Edge cases and special handling

**Known Issues**:
- Bugs or limitations
- Workarounds in place
- Plans for resolution

**Asset Dependencies**:
- External content needed
- Who's providing what
- Timeline and status

#### Consider Documenting [#consider-documenting]

**Story Context**:
- Target audience
- Tone and style guidelines
- Key themes or messages

**Testing Results**:
- What was tested
- Issues found
- Resolutions implemented

**Integration Points**:
- External systems or APIs
- Data formats
- Connection details

### What Not to Document [#what-not-to-document]

#### Don't Document Obvious Things [#dont-document-obvious-things]

**Obvious** (skip):
- "Scene 1 is named Introduction"
- "This is a text interaction"

**Useful** (document):
- "Scene 1 requires hasAccount=true after testing showed confusion for new users"

#### Don't Duplicate the UI [#dont-duplicate-the-ui]

**Redundant**:
```
Scene 2 connects to Scene 3
Scene 3 connects to Scene 4
```

**Better**:
```
# Linear Path (Scenes 2-7)
Tutorial sequence - no branching
Players must complete in order
```

## Templates and Examples [#templates-and-examples]

### Notebook Template [#notebook-template]

```markdown
# [Story Title] - Documentation

## Overview
**Purpose**: [What this story does]
**Audience**: [Who it's for]
**Length**: [Estimated play time]
**Status**: [In development / Testing / Complete]

## Story Structure
[High-level outline]

## Key Variables
| Variable | Type | Purpose | Set By |
|----------|------|---------|--------|
| playerName | string | Personalization | Scene 1 |
| trustScore | number | Relationship tracking | Multiple |

## Conditional Logic
[Complex logic explained]

## Assets
- [ ] Audio: Scene 3 background music
- [ ] Image: Character portrait
- [x] Text: Final copy approved

## Testing Notes
[Issues, feedback, resolutions]

## Change Log
**[Date]** - [What changed and why]
```

### Story Note Templates [#story-note-templates]

**Bug Report**:
```
BUG: [Description]
Impact: [High/Med/Low]
Found by: [Name]
```

**Task**:
```
TODO: [Action]
By: [Date/Person]
Blocks: [What depends on this]
```

**Question**:
```
ASK: [Question]
Context: [Why asking]
Needed by: [When]
```

## Next Steps [#next-steps]

- Implement the [Notebook Feature](/docs/v0-1/story-portal/notebook/notebook-feature) with these organizational strategies
- Use [Story Notes](/docs/v0-1/story-portal/notebook/story-notes) for canvas-based annotations following these guidelines
- Regularly review and update your documentation as your story evolves