Skip to main content

Notion Workspace Setup

This project uses Notion for task management, planning, and active work tracking.

Why Notion + Docusaurus?​

We use both systems with clear boundaries:

SystemPurpose
NotionActive work, planning, brainstorming, task tracking
DocusaurusTechnical docs, API references, guides (version-controlled)

Think of it as: Notion for the "now", Docs for the "forever"

Getting Started​

1. Access the Workspace​

See NOTION.md in the repo root for the workspace URL and quick links.

Don't reinvent the wheel! Notion has excellent templates:

  1. Open Notion
  2. Click "Templates" in the sidebar
  3. Browse to "Engineering" or "Product"
  4. Use one of these:
    • "Engineering Wiki" - Great starting point
    • "Sprint Board" - Agile sprint tracking
    • "Product Roadmap" - Feature planning
    • "Bug Tracker" - Simple bug database

Recommended combo:

  • Start with "Sprint Board" template
  • Add "Bug Tracker" template
  • Customize only if you need specific fields

3. If You Need Custom Databases​

Only create custom databases if the templates don't work for you.

Simple Custom Structure​

If templates don't fit, here's a minimal setup:

Features Database:

Properties:
- Name (title)
- Status (select: Planned, In Progress, Review, Done, Icebox)
- Priority (select: P0, P1, P2, P3)
- Effort (select: XS, S, M, L, XL)
- Sprint (relation to Sprints)
- Owner (person)
- GitHub Issue (URL)

Views:
- Kanban (by Status)
- Roadmap (timeline)
- By Priority (table)

Tasks Database:

Properties:
- Name (title)
- Status (select: Todo, In Progress, Complete, Blocked)
- Type (select: Feature, Bug, Chore, Docs)
- Feature (relation to Features)
- Assignee (person)
- Due Date (date)

Views:
- My Tasks (filtered by Assignee)
- Sprint Board (kanban by Status)
- All Tasks (table)

Bugs Database:

Properties:
- Name (title)
- Priority (select: Critical, High, Medium, Low)
- Status (select: New, Investigating, Fixing, Fixed, Won't Fix)
- Reported (date)
- Fixed In (text - version/commit)
- GitHub Issue (URL)

Views:
- Active Bugs (filtered: not Fixed/Won't Fix)
- By Priority (grouped)
- Closed (filtered: Fixed/Won't Fix)

Simple Workflow (Using Templates)​

Option A: Just Use Sprint Board Template​

  1. Add "Sprint Board" template from Notion
  2. It comes with:
    • ✅ Todo/In Progress/Done columns
    • ✅ Task assignments
    • ✅ Priorities
    • ✅ Dates
  3. Start using it immediately - no customization needed!

Option B: Combine Multiple Templates​

  1. "Sprint Board" for current work
  2. "Bug Tracker" for bugs
  3. "Roadmap" for planning

Link them together as you go.

Custom Sprint Setup (Advanced)​

Only do this if templates don't work. Create a Sprints Database:

Properties:
- Name (title) - e.g., "Sprint 3: Guild Roster Sync"
- Start Date (date)
- End Date (date)
- Status (select: Planning, Active, Complete)
- Goal (text)

Template:
## Sprint Goal
[What we want to achieve]

## Features
[Relation to Features Database]

## Tasks
[Relation to Tasks Database]

## Notes
[Daily updates, blockers, decisions]

Workflow​

Daily Work​

  1. Check Notion - See your tasks for the day
  2. Update status - Move cards as you work
  3. Add notes - Document blockers, decisions
  4. Link commits - Reference GitHub issues/PRs

Feature Completion​

When a feature is done:

  1. Mark feature as ✅ Done in Notion
  2. Document in Docusaurus if needed:
    • New API endpoints → docs/docs/api/
    • Architecture changes → docs/docs/architecture/
    • User guides → docs/docs/guides/
  3. Link from Notion to the docs page

Design Decisions​

  1. Brainstorm in Notion - Create RFC page
  2. Discuss and decide - Add comments, iterate
  3. Finalize in Docs - Create architecture doc
  4. Archive Notion page - Link to docs, mark as ✅ Decided

Tips​

Keep It Simple​

  • Don't over-engineer your workspace
  • Start with basic databases
  • Add complexity only when needed

Useful Views​

Quick Win View (Tasks):

  • Filter: Effort = XS or S
  • Sort: Priority (high to low)
  • Great for "what can I knock out quickly?"

Blocked View (Tasks):

  • Filter: Status = Blocked
  • Shows what needs attention

This Sprint (Features):

  • Filter: Sprint = Current Sprint
  • See what you committed to

Templates​

Create page templates for:

  • Sprint Planning
  • Feature Spec
  • Bug Report
  • Meeting Notes

Integration with GitHub​

Linking Issues​

Always cross-reference:

  • Notion task → Add GitHub issue URL
  • GitHub issue → Reference Notion task ID in description

Example GitHub issue:

## Context

See Notion task: `TASK-123`

## Description

[...]

When to Use Each​

GitHub Issues:

  • Bug reports from users
  • Feature requests from community
  • Technical discussions in comments

Notion:

  • Internal planning
  • Sprint organization
  • Private notes/decisions

Common Patterns​

Feature Development​

  1. Create feature in Notion
  2. Break into tasks
  3. Assign to sprint
  4. Create GitHub issues for each task
  5. Link issues in Notion
  6. Work and update both
  7. When done, document in Docusaurus

Bug Fixes​

  1. Report in GitHub Issues (public)
  2. Create Notion bug card (tracking)
  3. Investigate and update status
  4. Fix and close both
  5. Update docs if behavior changed

Maintenance​

Weekly​

  • Archive completed sprints
  • Clean up stale tasks
  • Review backlog priorities

Monthly​

  • Review roadmap
  • Archive old RFCs
  • Update documentation links

Remember: Notion is your workspace, Docs is your reference. Keep active work in Notion, finalized knowledge in Docs.