Skip to content

docs: Standardize README structure across ecosystem #561

Description

@kcenon

What

Define and apply a standard README section structure across all 8 ecosystem
projects. Currently section count varies significantly (container_system: 13
sections vs common_system: 35+ sections).

Why

Inconsistent README depth and organization makes cross-project navigation
difficult. Users familiar with one project's README layout must relearn the
structure for each sibling project. Consistent document structure dramatically
improves discoverability and reduces onboarding friction.

Where

Repository Current Sections Gap
common_system ~35 Minor reordering
thread_system ~40 Minor reordering
logger_system ~30 Minor reordering
container_system ~13 Significant expansion needed
monitoring_system ~23 Moderate expansion
database_system ~30 Minor reordering
network_system ~20 Moderate expansion
pacs_system ~12 Significant expansion needed

How

Standard README Template (13 sections)

1. Overview
   - Project purpose + core value proposition
   - Badge row (CI, coverage, license, version)

2. Key Features
   - Feature matrix table

3. Requirements
   - System requirements, compiler versions, dependencies

4. Quick Start
   - Minimal working example (< 20 lines)

5. Installation
   - vcpkg, CMake FetchContent, manual build

6. Architecture
   - Module structure diagram (Mermaid)
   - Key abstractions

7. Core Concepts
   - Essential concepts for understanding the library

8. API Overview
   - Key API summary table + link to API_REFERENCE.md

9. Examples
   - 3-5 representative usage examples

10. Performance
    - Benchmark summary table + link to BENCHMARKS.md

11. Ecosystem Integration
    - Dependency graph within kcenon ecosystem
    - Integration examples with sibling projects

12. Contributing
    - Link to CONTRIBUTING.md

13. License

Implementation Steps

  1. Create docs/README_TEMPLATE.md in common_system as the canonical template
  2. Audit each project's README against the template
  3. For under-documented projects (container, pacs, monitoring, network):
    • Add missing sections
    • Expand thin sections with content from existing docs/ files
  4. For well-documented projects (common, thread, logger, database):
    • Reorder sections to match standard
    • No content removal — only restructuring
  5. Ensure both README.md (English) and README.kr.md (Korean) are updated

Acceptance Criteria

  • docs/README_TEMPLATE.md exists in common_system
  • All 8 projects have all 13 standard sections in README.md
  • All 8 projects have matching README.kr.md updates
  • container_system README expanded to 13 standard sections with full content
  • pacs_system README expanded to 13 standard sections with full content
  • No existing content removed — only restructured or expanded

Related

Metadata

Metadata

Assignees

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions