Skip to main content

📖 Documentation Guidelines

This document defines the style, tone, and structure standards for all Springular documentation. Follow these guidelines to ensure consistency across all docs.

📚 Documentation as Source of Truth​

These guidelines are the authoritative reference for all documentation work. This documentation is the authoritative knowledge base for the project.

Rules​

  1. Before writing new docs: Read these guidelines, determine correct document type, check existing structure
  2. After writing docs: Verify compliance with guidelines, check consistency, confirm correct placement
  3. When implementing from docs: Follow documentation patterns and structure as the authoritative source
  4. After implementation: Update docs if implementation differs, ensure documentation reflects reality

For contributors and AI assistants: Always reference these guidelines when creating or modifying documentation. When implementing features from Epic/Implementation Guide documentation, treat those docs as the source of truth and follow their defined patterns.

Escape hatch: Rules can be bent with justification, not ignored. This prevents silent rule-breaking while allowing necessary flexibility.

TL;DR — Quick Decision Guide​

Where does my doc go?

Is it...→ Document Type→ Location (Lifecycle Stage)
Implemented & shipped?FeatureFeatures → Implemented
Step-by-step code guide?Implementation GuideImplementation Guides → Execution
System design?Solution ArchitecturePlanned Features → Planning & Design
Capability goal?EpicPlanned Features → Planning & Design
Strategy/analysis?Strategy DocConstellation → Strategy
How to use Springular?Developer GuideDeveloper Guide

Format rules:

  1. Title + emoji (one emoji per title)
  2. 1-3 sentence introduction
  3. Clear sections (Overview → Usage → Config)
  4. Direct tone, no marketing fluff
  5. Present tense, active voice

Golden Rule: If it's not implemented, it's NOT a Feature doc.

Lifecycle labels (use these in structure, without brackets):

  • Strategy: Why we build, evidence, roadmap
  • Planning & Design: Epics and Solution Architecture
  • Execution: Implementation Guides (step-by-step)
  • Implemented: Features (production-ready)

Document Organization​

File Naming Conventions​

TypePatternLocationExample
Epicepic.mdconstellation/{capability}/text-intelligence/epic.md
Solution Architecturearchitecture.mdconstellation/{capability}/text-intelligence/architecture.md
Implementation Guide{name}.mdconstellation/{capability}/text-intelligence/foundation.md
Feature{name}.mddocs/auth.md

Note: Implementation guides use capability abbreviation prefix in titles (e.g., "TI: Foundation"), not in filenames.

📚 Developer Guide
  - Getting started, project structure, CI/CD, deployment

🌌 Constellation → Strategy
  - Analysis (POC learnings)
  - Business Patterns (TrustMRR validation)
  - Roadmap (what we build, when, why)

🔨 Boilerplate Enhancements → Planning & Design
  - 🎯 Epic
  - 🏗️ Solution Architecture
  - 🛠️ Implementation Guides

🛠️ Text Operations → Planning & Design
  - 🎯 Epic
  - 🏗️ Solution Architecture
  - 🛠️ Implementation Guides

⭐ Features → Implemented
  - Authentication, Payments, Emails, Themes

Grouping Logic: Documents are grouped by domain (technical capability area). Each domain contains its Epic, Solution Architecture, and Implementation Guides together for better discoverability and cohesion.

Document Types & Lifecycle​

TypePurposeLocationLifecycleKey Rule
FeatureUser-facing, production-ready capabilityFeatures → ImplementedFinal stateOnly when shipped & validated
Implementation GuideStep-by-step code instructionsImplementation Guides → ExecutionLong-livedAnswers "how" questions
Solution ArchitectureSystem design & patternsPlanned Features → Planning & DesignLong-livedAnswers "what/why" questions
EpicCapability goal definitionPlanned Features → Planning & DesignTemporaryArchived after validation

Feature​

What it is: User-facing capability that's implemented, tested, and production-ready.

Key rules:

  • Only create after implementation is complete
  • Must have clear API or user interface
  • Provides direct value to users or developers
  • Examples: Authentication, Payments, Emails

What it is NOT: Planning docs, implementation guides, architecture docs, strategy docs.

Epic​

What it is: Temporary capability-definition document that validates Constellation enhancements.

Key rules:

  • Defines concrete, product-shaped goal
  • Sets scope boundaries and success criteria
  • Temporary (archived after fork product validation)
  • Links to Solution Architecture and Implementation Guides

Location: constellation/{capability}/epic.md

See: Text Intelligence Epic for example.

Solution Architecture​

What it is: Long-lived system design document defining how capabilities are structured.

Key rules:

  • Business-agnostic (no product-specific logic)
  • Explains design decisions, patterns, and constraints
  • Defines extension points and boundaries
  • Does NOT contain: Step-by-step instructions, code snippets, DTO definitions

Location: constellation/{capability}/architecture.md

Implementation Guide​

What it is: Actionable, step-by-step guide for implementing specific features.

Key rules:

  • Code-heavy (snippets, examples, DTOs)
  • Feature-specific (one guide per feature)
  • Can evolve as implementation evolves
  • Does NOT contain: High-level architecture, design rationale (reference Solution Architecture)

Location: constellation/{capability}/{feature-name}.md Title format: Use capability abbreviation prefix (e.g., "TI: Foundation", "TI: Generation")

Document Lifecycle​

Documents move through: Strategy → Planning & Design → Execution → Implemented

  1. Constellation → Strategy: Capability appears in roadmap
  2. Planned Features → Planning & Design: Epic defines goal, Solution Architecture designs system
  3. Implementation Guides → Execution: Step-by-step guides created during development
  4. Features → Implemented: Once implemented and validated, becomes feature documentation

Lifecycle details:

  • Epic: Temporary. Created → Validated → Archived
  • Solution Architecture: Long-lived. Created → Maintained → Reference
  • Implementation Guides: Long-lived. Created → Updated → Stays for contributors
  • Feature: Final state. Implemented → Validated → User-facing docs

Rule: Only move docs to Features → Implemented when capability is fully implemented, tested, production-ready, and validated via fork product.

Content Distribution​

Content TypeEpicSolution ArchitectureImplementation GuideFeature
Why this exists✅❌❌❌
Business value✅❌❌❌
Scope boundaries✅✅❌✅
System architecture❌✅❌❌
Design decisions❌✅❌❌
Step-by-step❌❌✅❌
Code snippets❌❌✅✅
API/usage docs❌❌❌✅

Rule: Each document type has a clear purpose. Don't duplicate content across document types. Use cross-references instead.

Style & Formatting​

Structure​

Document Header: Frontmatter with sidebar_position, then title with emoji.

Introduction: 1-3 sentences explaining what, why, who.

Sections: Use clear hierarchy (H1 → H2 → H3), title case.

Tone & Voice​

Use: Direct statements, action verbs, present tense, second person ("you").

Avoid: Passive voice, qualifiers ("might", "possibly"), marketing speak, over-explanation.

Style: Professional but friendly, clear without condescension.

Formatting Standards​

Emphasis:

  • Bold: Key terms (first mention), warnings, feature names, action items
  • Italic: File names, paths, code references in prose, emphasis (sparingly)
  • Code: File names, variables, properties, command arguments, config values

Lists:

  • Bullet points (-) for features, options, unordered items
  • Numbered lists (1.) for sequential steps, ordered procedures
  • Format: One item per line, capitalize first word, end with period for complete sentences

Code Blocks: Always specify language for syntax highlighting.

Tables: Use for comparisons, configurations, feature matrices, priorities.

Content Structure​

Common sections: Introduction → Overview → Configuration → Usage → Examples → Troubleshooting → References

Cross-references: Use clear, descriptive link text. Avoid "click here" or "see this link".

Platform Enhancement Docs​

Platform enhancement docs (in constellation/) use the capability folder structure: constellation/{capability-name}/ contains epic, architecture, and all implementation guides.

Strategic documents: Use tables for comparisons, callouts for context, bold for key principles, emojis in headers when appropriate.

Technical specifications: Use code blocks for examples, clear hierarchy, reference related docs.

See: Text Intelligence Epic for example.

Emoji Usage​

Use emojis in document titles (one emoji per title, required):

  • 🚀 Quick Start / Getting Started
  • 🔒 Authentication / Security
  • 💳 Payments / Billing
  • 🎨 Themes / Styling
  • 🗂️ Structure / Organization
  • ⚙️ Configuration
  • 📚 Guides / References
  • 🔍 Analysis / Research
  • 🗺️ Roadmaps / Strategy
  • 📊 Data / Analytics
  • 📝 Text / Writing
  • 🎯 Specifications / Targets

Rules: Use relevant emojis, keep it professional, avoid excessive emoji use in body text. Platform enhancement docs may use strategic emojis (✅, ⚠️, 🔧, 🎯) in section headers.

Language & Terminology​

Consistent Terms​

  • Springular — The boilerplate name (always capitalized)
  • Constellation — The enhanced version (capitalized)
  • Spring Boot — Backend framework (capitalized correctly)
  • Angular — Frontend framework (capitalized)
  • Stripe — Payment service (capitalized)

Technical Terms​

  • Use proper casing: application.yml (lowercase), not Application.yml
  • Use code formatting for technical terms: @Service, JWT, REST API
  • Explain acronyms on first use: JWT (JSON Web Token)

Avoiding Common Pitfalls​

Don't:

  • Duplicate information across docs — reference instead
  • Use vague language ("things", "stuff", "etc.")
  • Write walls of text — break into sections
  • Assume prior knowledge — explain key concepts
  • Mix tenses — use present tense consistently
  • Use passive voice when active is clearer

Do:

  • Be specific and clear
  • Use examples when helpful
  • Link to related documentation
  • Break complex topics into sections
  • Use tables for comparisons
  • Keep sentences and paragraphs concise

Review Checklist​

Before finalizing any documentation:

Documentation Guidelines Compliance:

  • Referenced these guidelines before writing
  • Verified consistency with existing docs of the same type
  • Confirmed correct document type and location
  • Verified lifecycle stage is correct (Strategy, Planning & Design, Execution, Implemented)

Structure & Format:

  • Document has clear title with appropriate emoji
  • Introduction explains what the doc covers (1-3 sentences)
  • Headers follow title case
  • Bold/italic/code formatting used correctly
  • Code blocks have language specified
  • Lists are formatted consistently
  • Links use descriptive text

Content Quality:

  • No duplicate information (reference other docs instead)
  • Tone is direct and actionable
  • Technical terms are explained or linked
  • Examples are relevant and clear

For Implementation: If implementing from documentation, verify documentation patterns are followed as the source of truth.

Examples​

See real documentation for examples: