StarPunk/docs/standards/documentation-organization.md

# Documentation Organization Standard

## Purpose

This document defines the organization and structure of all StarPunk documentation. It establishes clear guidelines for what types of documents belong where, naming conventions, and when to create each type.

## Philosophy

Documentation follows the same principle as code: "Every document must justify its existence." Documents should be:

- **Actionable**: Provide clear guidance for implementation
- **Discoverable**: Easy to find based on purpose
- **Maintainable**: Updated as decisions evolve
- **Minimal**: No redundant or unnecessary documentation

## Directory Structure

```
docs/
├── architecture/          # High-level system design and overviews
├── decisions/            # Architecture Decision Records (ADRs)
├── design/               # Detailed technical designs and specifications
└── standards/            # Coding standards, conventions, and guidelines
```

## Document Types

### 1. Architecture Documents (`docs/architecture/`)

**Purpose**: High-level system architecture, component relationships, and technology overviews.

**When to Create**:
- Describing the overall system architecture
- Documenting major subsystems and their interactions
- Explaining technology stack choices (overview)
- Defining deployment architecture
- Documenting security architecture
- Creating data flow diagrams

**Naming Convention**: `{topic}.md`

**Examples**:
- `overview.md` - System architecture overview
- `components.md` - Component descriptions and relationships
- `data-flow.md` - How data moves through the system
- `security.md` - Security architecture and threat model
- `deployment.md` - Deployment architecture and strategies
- `technology-stack.md` - Complete technology stack with rationale

**Characteristics**:
- Broad scope, high-level view
- Focus on "what" and "why" at system level
- Includes diagrams and visual representations
- Describes component interactions
- Documents architectural patterns
- References relevant ADRs

**Template Structure**:
```markdown
# {Topic} Architecture

## Overview
[High-level description]

## Components
[Major components and their roles]

## Interactions
[How components communicate]

## Patterns
[Architectural patterns employed]

## Diagrams
[Visual representations]

## References
[Links to related ADRs and design docs]
```

---

### 2. Architecture Decision Records (`docs/decisions/`)

**Purpose**: Document significant architectural decisions with context, rationale, and alternatives considered.

**When to Create**:
- Selecting technologies or libraries
- Choosing between architectural approaches
- Making trade-offs that affect multiple components
- Establishing patterns or standards
- Accepting technical debt
- Rejecting common alternatives

**Naming Convention**: `ADR-{NNN}-{short-title}.md`
- NNN = Zero-padded sequential number (001, 002, etc.)
- short-title = Kebab-case description

**Examples**:
- `ADR-001-python-web-framework.md`
- `ADR-002-flask-extensions.md`
- `ADR-003-frontend-technology.md`
- `ADR-004-file-based-note-storage.md`
- `ADR-005-indielogin-authentication.md`
- `ADR-006-python-virtual-environment-uv.md`

**Characteristics**:
- Focused on a single decision
- Documents the decision-making process
- Includes evaluation criteria
- Lists alternatives considered with scores
- Explains trade-offs and consequences
- Has a status (Proposed, Accepted, Superseded)
- Immutable once accepted (new ADR to change)

**Required Template**:
```markdown
# ADR-{NNN}: {Title}

## Status
{Proposed|Accepted|Superseded by ADR-XXX}

## Context
What is the issue we're addressing? What are the requirements?
What constraints do we face?

## Decision
What have we decided? Be specific and clear.

## Rationale
Why did we make this decision?

### {Technology/Approach} Score: X/10
- Simplicity Score: X/10 - [explanation]
- Fitness Score: X/10 - [explanation]
- Maintenance Score: X/10 - [explanation]
- Standards Compliance: Pass/Fail - [explanation]

## Consequences

### Positive
- [List benefits]

### Negative
- [List drawbacks]

### Mitigation
- [How we address drawbacks]

## Alternatives Considered

### {Alternative 1} (Rejected/Considered)
- Simplicity: X/10 - [explanation]
- Fitness: X/10 - [explanation]
- Maintenance: X/10 - [explanation]
- Verdict: [Why rejected]

### {Alternative 2} (Rejected/Considered)
[Same structure]

## Implementation Notes
[Any specific guidance for implementing this decision]

## References
- [Links to specifications, documentation, related ADRs]
```

**Status Values**:
- **Proposed**: Decision is under consideration
- **Accepted**: Decision is final and should be implemented
- **Superseded**: Decision has been replaced (link to new ADR)

**Numbering Rules**:
- Numbers are sequential starting from 001
- Never reuse or skip numbers
- Numbers are assigned when ADR is created, not when accepted
- Numbers provide chronological history

---

### 3. Design Documents (`docs/design/`)

**Purpose**: Detailed technical specifications for implementation, including schemas, APIs, file formats, and component interfaces.

**When to Create**:
- Defining database schemas
- Specifying API contracts and endpoints
- Designing file formats and structures
- Defining component interfaces
- Specifying configuration formats
- Documenting project structure
- Creating initial setup specifications

**Naming Convention**: `{component-or-feature}.md`

**Examples**:
- `project-structure.md` - Complete directory and file organization
- `database-schema.md` - Database tables, columns, indexes, relationships
- `api-contracts.md` - RESTful API endpoint specifications
- `micropub-endpoint.md` - Micropub API implementation details
- `rss-feed-format.md` - RSS feed structure and generation
- `ui-patterns.md` - User interface patterns and components
- `component-interfaces.md` - How components communicate
- `initial-files.md` - Bootstrap files and configurations
- `authentication-flow.md` - Detailed auth implementation

**Characteristics**:
- Detailed and specific
- Implementation-ready specifications
- Includes code examples, schemas, formats
- Defines exact file contents when applicable
- Provides acceptance criteria
- Focus on "how" at implementation level
- Should be sufficient for developer to implement

**Template Structure**:
```markdown
# {Component/Feature} Design

## Purpose
[What this component/feature does]

## Overview
[High-level description]

## Specification

### {Aspect 1}
[Detailed specification with examples]

### {Aspect 2}
[Detailed specification with examples]

## Implementation Details

### File Structure
[If applicable]

### API Endpoints
[If applicable]

### Database Schema
[If applicable]

### Configuration
[If applicable]

## Examples
[Concrete examples of usage]

## Acceptance Criteria
[How to verify correct implementation]

## References
[Related ADRs, standards, specifications]
```

---

### 4. Standards Documents (`docs/standards/`)

**Purpose**: Establish coding conventions, development practices, and guidelines that ensure consistency.

**When to Create**:
- Defining coding style guidelines
- Establishing naming conventions
- Documenting development setup procedures
- Creating testing standards
- Defining commit message formats
- Establishing documentation standards
- Setting API design principles

**Naming Convention**: `{topic}-standards.md` or `{topic}-setup.md`

**Examples**:
- `documentation-organization.md` - This document
- `python-coding-standards.md` - Python style guide
- `development-setup.md` - Setup procedures
- `testing-strategy.md` - Testing approach and standards
- `api-design.md` - API design principles
- `indieweb-compliance.md` - How to meet IndieWeb specs
- `commit-conventions.md` - Git commit standards

**Characteristics**:
- Prescriptive and normative
- Define consistent practices
- Include examples of good/bad patterns
- Focus on "how we work"
- Living documents (updated as practices evolve)
- Should include rationale for standards

**Template Structure**:
```markdown
# {Topic} Standards

## Purpose
[Why these standards exist]

## Principles
[Core principles underlying the standards]

## Standards

### {Standard Category 1}
[Detailed standard with examples]

**Good Example**:
```[code/example]
```

**Bad Example**:
```[code/example]
```

**Rationale**: [Why this is the standard]

### {Standard Category 2}
[Same structure]

## Enforcement
[How standards are enforced - tools, reviews, etc.]

## Exceptions
[When it's acceptable to deviate]

## References
[Related standards, tools, specifications]
```

---

## Cross-References

Documents should reference each other appropriately:

- **ADRs** → Should be referenced by Architecture, Design, and Standards docs
- **Architecture** → References ADRs, links to Design docs
- **Design** → References ADRs, may reference Standards
- **Standards** → May reference ADRs for rationale

**Reference Format**:
```markdown
See [ADR-001: Python Web Framework](/home/phil/Projects/starpunk/docs/decisions/ADR-001-python-web-framework.md)
See [Database Schema Design](/home/phil/Projects/starpunk/docs/design/database-schema.md)
See [Python Coding Standards](/home/phil/Projects/starpunk/docs/standards/python-coding-standards.md)
```

## Document Lifecycle

### Creating Documents

1. **Determine Type**: Which category does this belong in?
2. **Check for Existing**: Does a similar document already exist?
3. **Name Appropriately**: Follow naming conventions
4. **Use Template**: Start from the appropriate template
5. **Be Specific**: Include actionable details
6. **Reference Related Docs**: Link to ADRs and other docs

### Updating Documents

**ADRs**: Once accepted, ADRs are immutable. To change a decision:
- Create a new ADR
- Reference the old ADR
- Mark old ADR as "Superseded by ADR-XXX"

**Other Documents**: Living documents that should be updated:
- Add changelog section if document changes significantly
- Update references when related docs change
- Keep in sync with actual implementation

### Deprecating Documents

**Don't Delete**: Mark as deprecated instead
- Add "DEPRECATED" to title
- Add note explaining why and what replaced it
- Keep for historical reference

## Quality Checklist

Before finalizing any document:

- [ ] Is this the right document type for this content?
- [ ] Is the file in the correct directory?
- [ ] Does it follow the naming convention?
- [ ] Does it use the appropriate template?
- [ ] Is the content actionable and specific?
- [ ] Are all references correct and complete?
- [ ] Are there code examples where helpful?
- [ ] Is the rationale clear?
- [ ] Can a developer implement from this?
- [ ] Have I removed unnecessary content?

## Anti-Patterns

**Avoid**:
- Mixing document types (ADR with design specs)
- Redundant documentation (saying same thing in multiple places)
- Vague specifications ("should be fast", "user-friendly")
- Missing rationale (standards without explaining why)
- Orphaned documents (not referenced anywhere)
- Documentation for documentation's sake
- Copy-pasting without adapting

## Tools and Automation

**Validation**:
- Check links: Ensure all references point to existing files
- Naming validation: Verify naming conventions
- Template compliance: Ensure required sections exist

**Future Enhancements** (V2):
- Automated ADR numbering
- Documentation index generator
- Link checker
- Template enforcement

## Examples

### When to Create Which Document Type

**Scenario**: Choosing between SQLite and PostgreSQL

→ Create an ADR (`ADR-007-database-engine.md`)
- This is a technology decision
- Needs evaluation of alternatives
- Has long-term architectural impact

**Scenario**: Defining the exact database schema

→ Create a Design doc (`database-schema.md`)
- This is detailed specification
- Implementation-ready
- May evolve as requirements change

**Scenario**: Establishing how to write database migrations

→ Create a Standards doc (`database-migration-standards.md`)
- This is a practice/process
- Defines consistent approach
- Applies to all database changes

**Scenario**: Explaining how authentication, database, and file storage work together

→ Create an Architecture doc or update existing (`architecture/overview.md`)
- This is system-level interaction
- Cross-component relationship
- High-level understanding

## Summary

| Type | Purpose | Location | Mutability | Naming |
|------|---------|----------|------------|--------|
| **Architecture** | System-level design | `docs/architecture/` | Living | `{topic}.md` |
| **ADR** | Decision records | `docs/decisions/` | Immutable | `ADR-{NNN}-{title}.md` |
| **Design** | Implementation specs | `docs/design/` | Living | `{component}.md` |
| **Standards** | Coding/process guidelines | `docs/standards/` | Living | `{topic}-standards.md` |

## Principles Summary

1. **One Document Type Per File**: Don't mix ADR with Design specs
2. **Right Place, Right Name**: Follow conventions strictly
3. **Actionable Content**: Documentation should enable implementation
4. **Minimal but Complete**: Every document must justify its existence
5. **Reference Richly**: Link to related documents
6. **Update Living Docs**: Keep non-ADR docs current
7. **Never Delete**: Deprecate instead for historical reference

## References

- Michael Nygard's ADR pattern: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- Arc42 documentation: https://arc42.org/
- Diátaxis documentation framework: https://diataxis.fr/