By Patrick McCurley

Best Practices

By Patrick McCurley · Created Mar 21, 2026 public

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.

Spaces: Name after the domain, not the team.

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

  1. Publish a draft — /ember-publish your work-in-progress
  2. Share the link — Drop it in the relevant Slack channel
  3. Collect comments — Reviewers comment directly on specific blocks
  4. Iterate — Update the doc (same slug overwrites) based on feedback
  5. 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."