Documentation Best Practices

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

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

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

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

Structure and Organization

Use Consistent Headings

Create a standard structure for all your stories:

# 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

Use heading levels to show relationships:

# 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

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

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

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

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

Don't delete—archive at bottom:

# Active Documentation
(current information)

---

# Archive

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

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

Writing Effective Notes

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

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

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

Organize notes by type through position:

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

Note Lifecycle Management

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

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

Shared Notebook Guidelines

Since the Notebook is shared with all collaborators:

Use Sections for Different Roles

# 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

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

Mark sections actively being edited:

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

Multi-Author Story Notes

Story Notes show author names, enabling collaborative feedback:

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

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

What to 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

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

Don't 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

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

Notebook Template

# [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

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

• Implement the Notebook Feature with these organizational strategies
• Use Story Notes for canvas-based annotations following these guidelines
• Regularly review and update your documentation as your story evolves