Best Practices

Team conventions for publishing and collaborating on docs.

When to Publish vs Share a Link

Scenario	Action
Architecture decision, investigation, plan	Publish — it's a reference others will come back to
Quick code snippet or config	Paste in Slack — not worth a permanent doc
Meeting notes with action items	Publish — people can comment on specific items
One-off data export	Publish as dataset — sortable/searchable beats a CSV attachment
Recurring report	Publish and update — same slug, always current

Naming Conventions

Documents: Describe the content, not the action. Use lowercase with hyphens.

auth-flow-overview not document-about-auth
q1-churn-analysis not churn-data-march-2025
checkout-502-investigation not bug-report-3

Spaces: Name after the domain, not the team.

api-docs not backend-team-docs
onboarding-guide not new-hire-stuff

Organizing a Space

Use sections to group related pages. Keep the top level to 3-5 items max.

Overview              ← always first
Getting Started
  Installation
  Quick Start
Reference
  Skills
  Subagents
  API Endpoints
Guides
  Best Practices
  Troubleshooting

Rule of thumb: If a section has more than 7 pages, split it into two sections.

Review Workflow

Publish a draft — /ember-publish your work-in-progress
Share the link — Drop it in the relevant Slack channel
Collect comments — Reviewers comment directly on specific blocks
Iterate — Update the doc (same slug overwrites) based on feedback
Finalize — Remove any "DRAFT" labels, share the final link

Comments are per-block. Every heading, paragraph, table, and diagram is independently commentable. Point reviewers to specific sections rather than asking them to "review the whole thing."