|
| 1 | +--- |
| 2 | +authors: |
| 3 | +- Martin Stühmer |
| 4 | + |
| 5 | +applyTo: |
| 6 | +- "README.md" |
| 7 | +- "templates/readme-solution.md" |
| 8 | + |
| 9 | +created: 2026-01-10 |
| 10 | + |
| 11 | +lastModified: 2026-01-10 |
| 12 | + |
| 13 | +state: accepted |
| 14 | + |
| 15 | +instructions: | |
| 16 | + MUST use the standardized solution-level README template from templates/readme-solution.md for all repository-level documentation. |
| 17 | + MUST preserve existing content markers (e.g., <!-- packages:start -->) when modernizing existing README files. |
| 18 | + MUST include all required sections: Overview, Projects, Features, Getting Started, Development, Architecture, Contributing, Code of Conduct, Documentation, Versioning, Support, and License. |
| 19 | + MUST use relative links for all internal repository references (CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE, decisions/). |
| 20 | + MUST provide comprehensive guidance for each section through inline comments. |
| 21 | +--- |
| 22 | +# Standardized Solution-Level Documentation |
| 23 | + |
| 24 | +This decision establishes a standardized template for solution-level README files to ensure consistency, maintainability, and comprehensive documentation across all repositories. |
| 25 | + |
| 26 | +## Context |
| 27 | + |
| 28 | +Repository README files serve as the primary entry point for developers, contributors, and users. Without a standardized approach, documentation quality, structure, and completeness vary significantly across projects. This inconsistency creates several challenges: |
| 29 | + |
| 30 | +* New contributors struggle to understand project structure and getting started procedures |
| 31 | +* Essential information (contributing guidelines, architecture decisions, support channels) is inconsistently documented or missing |
| 32 | +* Modernizing documentation requires significant effort due to lack of common structure |
| 33 | +* Cross-referencing between documentation files (CONTRIBUTING.md, CODE_OF_CONDUCT.md, ADRs) is inconsistent |
| 34 | +* Maintenance burden increases as each repository uses different documentation patterns |
| 35 | + |
| 36 | +The need for a standardized, maintainable template became apparent as repositories grew and required regular documentation updates. A template-based approach enables consistent structure while preserving repository-specific content and custom markers. |
| 37 | + |
| 38 | +## Decision |
| 39 | + |
| 40 | +Adopt a standardized template for solution-level README files (`templates/readme-solution.md`) with specific sections, formatting conventions, and comprehensive inline guidance. |
| 41 | + |
| 42 | +The template includes: |
| 43 | + |
| 44 | +1. **Standard Structure**: Overview, Projects, Features, Getting Started, Development, Architecture, Contributing, Code of Conduct, Documentation, Versioning, Support, License, Maintainers, and Acknowledgments sections |
| 45 | +2. **Relative Links**: All internal references use relative paths (e.g., `[CONTRIBUTING.md](CONTRIBUTING.md)`) |
| 46 | +3. **Inline Guidance**: HTML comments provide detailed instructions for each section |
| 47 | +4. **Badge Support**: Standardized badges for license, build status, and contributors |
| 48 | +5. **Placeholder Patterns**: Consistent use of `YourRepo`, `ProjectName`, and similar placeholders for easy customization |
| 49 | +6. **Flexible Structure**: Optional sections (Maintainers, Acknowledgments, Configuration) can be removed if not needed |
| 50 | +7. **Marker Preservation**: Support for preserving existing content markers (e.g., `<!-- packages:start -->`, `<!-- packages:end -->`) during modernization |
| 51 | +8. **GitVersion Integration**: Documents the use of automated semantic versioning |
| 52 | +9. **Conventional Commits Reference**: Links to commit message standards |
| 53 | +10. **ADR Integration**: References Architecture Decision Records with relative links to `decisions/` folder |
| 54 | + |
| 55 | +When modernizing existing README files: |
| 56 | +* MUST preserve all existing content markers (comments like `<!-- packages:start -->`) |
| 57 | +* MUST retain existing content where applicable while restructuring to match template sections |
| 58 | +* MUST maintain any custom sections that provide repository-specific value |
| 59 | +* MUST update links to use relative paths consistently |
| 60 | + |
| 61 | +## Consequences |
| 62 | + |
| 63 | +### Positive |
| 64 | + |
| 65 | +* **Consistency**: All repositories follow the same documentation structure, improving navigation and comprehension |
| 66 | +* **Completeness**: Template ensures all essential sections are present and documented |
| 67 | +* **Maintainability**: Centralized template allows updating documentation standards across all repositories |
| 68 | +* **Onboarding**: New contributors can quickly understand project structure, setup, and contribution process |
| 69 | +* **Discoverability**: Standard sections make it easier to find specific information (architecture, testing, support) |
| 70 | +* **Cross-referencing**: Relative links create a cohesive documentation ecosystem connecting README, CONTRIBUTING.md, CODE_OF_CONDUCT.md, and ADRs |
| 71 | +* **Automation-friendly**: Consistent structure enables automated documentation checks and updates |
| 72 | +* **Backward Compatibility**: Marker preservation ensures existing automation and tooling continues to work during modernization |
| 73 | + |
| 74 | +### Negative |
| 75 | + |
| 76 | +* **Initial Effort**: Existing repositories require one-time modernization effort to adopt the template |
| 77 | +* **Customization Constraints**: Highly specialized repositories may need to adapt template sections |
| 78 | +* **Maintenance Overhead**: Template updates may require propagating changes to all repositories using it |
| 79 | +* **Learning Curve**: Contributors need to familiarize themselves with template structure and placeholder patterns |
| 80 | + |
| 81 | +### Trade-offs |
| 82 | + |
| 83 | +* Prioritizes consistency over complete flexibility in documentation structure |
| 84 | +* Requires initial time investment for long-term maintainability gains |
| 85 | +* May include sections not relevant to all repository types (can be removed as documented) |
| 86 | + |
| 87 | +## Alternatives Considered |
| 88 | + |
| 89 | +### No Template / Freeform Documentation |
| 90 | + |
| 91 | +**Description**: Allow each repository to define its own README structure without standardization. |
| 92 | + |
| 93 | +**Pros**: |
| 94 | +* Maximum flexibility for repository-specific needs |
| 95 | +* No migration effort required |
| 96 | +* Each team can optimize for their specific use case |
| 97 | + |
| 98 | +**Cons**: |
| 99 | +* Inconsistent documentation quality and completeness across repositories |
| 100 | +* Higher maintenance burden as each repository evolves independently |
| 101 | +* Poor discoverability for users navigating multiple repositories |
| 102 | +* Difficult to enforce documentation standards |
| 103 | +* No economies of scale for documentation improvements |
| 104 | + |
| 105 | +**Rejection Rationale**: The cost of inconsistency and maintenance burden outweighs the flexibility benefits. Standardization improves the experience for all stakeholders. |
| 106 | + |
| 107 | +### Wiki-Based Documentation |
| 108 | + |
| 109 | +**Description**: Use GitHub Wiki or external documentation platforms instead of README files. |
| 110 | + |
| 111 | +**Pros**: |
| 112 | +* More powerful formatting and organization capabilities |
| 113 | +* Separate documentation from code repository |
| 114 | +* Easier to maintain large documentation sets |
| 115 | + |
| 116 | +**Cons**: |
| 117 | +* Separate from codebase, harder to keep synchronized |
| 118 | +* Not visible in repository root for quick reference |
| 119 | +* Requires additional access management |
| 120 | +* Less portable (tied to specific platform) |
| 121 | +* README files remain necessary for initial overview |
| 122 | + |
| 123 | +**Rejection Rationale**: README files are essential for repository discoverability and initial orientation. Wiki can complement but not replace solution-level README. |
| 124 | + |
| 125 | +### Minimal README with External Links |
| 126 | + |
| 127 | +**Description**: Keep README minimal and link to external documentation sites. |
| 128 | + |
| 129 | +**Pros**: |
| 130 | +* Reduced repository clutter |
| 131 | +* More sophisticated documentation tooling available |
| 132 | +* Better version control for documentation history |
| 133 | + |
| 134 | +**Cons**: |
| 135 | +* Requires maintaining separate documentation infrastructure |
| 136 | +* Higher barrier to contribution (separate system to learn) |
| 137 | +* Documentation less accessible for offline or restricted environments |
| 138 | +* External dependencies for basic project information |
| 139 | + |
| 140 | +**Rejection Rationale**: Essential information should be readily available in the repository. External documentation can supplement but not replace core README content. |
| 141 | + |
| 142 | +## Related Decisions |
| 143 | + |
| 144 | +* [Folder Structure and Naming Conventions](./2025-07-10-folder-structure-and-naming-conventions.md) - Defines where documentation and templates are organized |
| 145 | +* [English as Project Language](./2025-07-11-english-as-project-language.md) - Establishes language requirements for all documentation |
| 146 | +* [GitVersion Automated Semantic Versioning](./2025-07-10-gitversion-automated-semantic-versioning.md) - Referenced in the Versioning section of the template |
| 147 | +* [Conventional Commits](./2025-07-10-conventional-commits.md) - Referenced in Contributing and Versioning sections |
0 commit comments