Skip to content

Latest commit

 

History

History
237 lines (167 loc) · 9.5 KB

DOCUMENTATION.md

File metadata and controls

237 lines (167 loc) · 9.5 KB

EmberDocs Documentation Index

Last Updated: 2026-01-02
Purpose: Complete reference guide to all documentation in the EmberDocs repository

Quick Navigation

Developer Documentation

Located in dev-docs/ - All developer-facing documentation including technical specs, guides, planning, and progress logs.

Technical Specifications (dev-docs/specs/)

Document Description Size
EMBERDOCS-TECHNICAL-SPEC.md Complete technical overview, architecture, and system design ~28KB
EMBERDOCS-API-SPEC.md REST and GraphQL API endpoints and contracts ~17KB
EMBERDOCS-DATABASE-SCHEMA.md PostgreSQL schema with Prisma ORM (for premium features) ~26KB
EMBERDOCS-ROADMAP.md 16-week development timeline and phased plan ~18KB

Development Guides (dev-docs/guides/)

Document Description Purpose
ARCHITECTURE-DECISIONS.md Architecture Decision Log (ADL) - "Why" behind major technical choices Reference locked decisions
DEVELOPMENT-STANDARDS.md Universal development standards (code style, testing, Git workflow) Coding guidelines
DEV-SETUP-VERIFICATION.md Local environment setup checklist and verification steps Onboarding
FEATURE-DEPENDENCIES.md Dependency graphs, critical path analysis, risk matrix Planning

Planning Documents (dev-docs/planning/)

Document Description
mvp_phase01of02.md Phase 01 detailed deliverables (D1.1-D1.9)
mvp_phase02of02.md Phase 02 detailed deliverables (D2.1-D2.9)
cli_tool_implementation.md CLI tool design and implementation plan
deferred_frontmatter_ui_editor.md Deferred feature documentation

Progress Logs (dev-docs/progress/)

Daily work logs following format: YYYY_MM_DD.md or YYYY_MM_DD_description.md

Recent logs:

Other Developer Docs (dev-docs/)

Document Description
PROJECT-OVERVIEW.md Complete package overview and quick start guide
USER-STORIES.md User personas and stories
EMBERDOCS-LICENSING.md Licensing model and terms
ACCESSIBILITY-AUDIT.md Accessibility audit results and compliance
Setup.md Installation and initial configuration
Deployment.md Production deployment instructions
Quick-Reference.md Developer cheat sheet (common commands, patterns, FAQ)

User Documentation

Located in dev-docs/ - Setup, deployment, and usage guides for developers and end users.

Note: User documentation is now located in dev-docs/ alongside developer documentation. The distinction is:

  • Developer docs (specs/, guides/, planning/, progress/): Technical documentation for contributors
  • User docs (Setup.md, Deployment.md, Quick-Reference.md): Guides for using and deploying EmberDocs

Naming Convention: Title Case (e.g., Setup.md, Deployment.md, Quick-Reference.md)

Example Documentation

Located in docs/examples/ - Sample documentation files used for testing and demonstration.

These files are served as example content in the documentation site and follow standard markdown with YAML frontmatter.

Structure:

  • docs/examples/index.md - Homepage
  • docs/examples/getting-started/ - Getting started guides
  • docs/examples/guides/ - Usage guides
  • docs/examples/api-reference/ - API reference documentation
  • docs/examples/deep/ - Deep nesting examples

Note: These are example files, not developer documentation. They demonstrate how users would structure their own documentation.

Root-Level Documentation

Project overview and contributor guidelines at repository root.

Document Description Audience
README.md Project overview, quick start, features Everyone
AGENTS.md Contributing guidelines and workflow Contributors
claude.md Detailed contributor guidelines Contributors
CHANGELOG.md Version history and changes Everyone
NOTICES.md Third-party license notices Legal/Compliance
LICENSE Core framework license Everyone

Brand & Design Documentation

Located in brand/ and mockups/ directories.

Brand (brand/)

Document Description
EMBERDOCS-STYLE-GUIDE.md Complete design system (colors, typography, components)
emberdocs-brand-guidelines.md Logo usage and brand identity

Mockups (mockups/)

Directory Description
mockups/ui/ Application UI screen designs
mockups/landing/ Marketing landing page variations
mockups/bw/ Black and white mockups

See UI-MOCKUPS-GUIDE.md and LANDING-MOCKUPS-GUIDE.md for details.

Naming Conventions

Developer Documentation (dev-docs/)

Format: ALL CAPS with hyphens
Examples:

  • ARCHITECTURE-DECISIONS.md
  • DEVELOPMENT-STANDARDS.md
  • EMBERDOCS-TECHNICAL-SPEC.md
  • EMBERDOCS-API-SPEC.md

Organization:

  • dev-docs/specs/ - Technical specifications
  • dev-docs/guides/ - Development guides
  • dev-docs/planning/ - Phase plans and planning docs
  • dev-docs/progress/ - Daily progress logs

User Documentation (dev-docs/)

Format: Title Case with hyphens
Examples:

  • Setup.md
  • Deployment.md
  • Quick-Reference.md

Example Documentation (docs/examples/)

Format: kebab-case (standard markdown naming)
Examples:

  • getting-started.md
  • basic-usage.md
  • api-reference.md

Finding Documentation

By Purpose

Getting Started:

  1. README.md - Project overview
  2. dev-docs/Setup.md - Installation
  3. dev-docs/Quick-Reference.md - Common commands

Understanding Architecture:

  1. dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md - System design
  2. dev-docs/guides/ARCHITECTURE-DECISIONS.md - Decision log
  3. dev-docs/specs/EMBERDOCS-API-SPEC.md - API design

Contributing:

  1. AGENTS.md - Contributing workflow
  2. dev-docs/guides/DEVELOPMENT-STANDARDS.md - Coding standards
  3. dev-docs/guides/DEV-SETUP-VERIFICATION.md - Setup verification

Planning:

  1. dev-docs/specs/EMBERDOCS-ROADMAP.md - Development timeline
  2. dev-docs/planning/mvp_phase01of02.md - Phase 01 plan
  3. dev-docs/guides/FEATURE-DEPENDENCIES.md - Dependency analysis

Documentation Maintenance

When to Update

  • Technical Specs (dev-docs/specs/): When architecture or API changes
  • Architecture Decisions (dev-docs/guides/ARCHITECTURE-DECISIONS.md): When making major technical decisions
  • Progress Logs (dev-docs/progress/): Daily (end of work day)
  • User Docs (dev-docs/): When features change or new setup steps added
  • README.md: When project overview or quick start changes

Cross-References

All documentation should cross-reference related documents. Use relative paths:

  • dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md
  • dev-docs/guides/ARCHITECTURE-DECISIONS.md
  • dev-docs/Quick-Reference.md

Quick Reference

Most Frequently Used:

For New Contributors:

  1. Read README.md
  2. Follow dev-docs/guides/DEV-SETUP-VERIFICATION.md
  3. Review AGENTS.md
  4. Bookmark dev-docs/Quick-Reference.md

Last Updated: 2026-01-02
Maintained by: EmberDocs Team