Living Documentation generates a project's documentation from what its repository already holds: User Story,
Feature and Functionality headers in source code, and Gherkin .feature files. The documentation is regenerated on
every run, so it never drifts from the work. This repository is the ecosystem's entry: the concept, the shape of the
system, the format canon, and one card per repository.
This documentation describes v0.1.0. For another tag, see that release's notes.
I want documentation out of my repository.
- Living Documentation in 5 Minutes: is this for me, and what do I prepare?
- Choosing a documentation source: what the pipeline mines.
- Build a pipeline: collect, normalize, generate, and the tutorial to copy.
I write the User Stories.
- Authoring documentation: write it like this.
- Authoring formats and Glossary: the exact layouts and the entity model.
- Example corpus: a worked mini project to copy.
I build on these contracts, or change this repository.
- Projects: which repository does what.
- Contracts: the six contracts, and which component writes and reads each.
- CONTRIBUTING.md: branches, pull requests, the page rules and the checks.
An author writes each User Story, Feature and Functionality once, as a header in source code, by hand or with the optional AI layer. A collector mines the headers and the test scenarios, the toolkit normalizes them into one canonical shape, and a generator renders a document from it. Each stage is a GitHub Action, and the pipeline runs AI-free. GitHub issues and Azure DevOps work items as sources, and PDF output, are planned.
- The concept and the problem it solves: What is Living Documentation?
- The stages and how one run flows: Architecture
- What each part does and must not do: Principles
- The three documents a pipeline renders: Document types
- Glossary: the entity model, the IDs and the acceptance-criterion grammar.
- Authoring formats: the exact header layouts an author writes.
- Rendering rules: what each view of a document shows, and how coverage is counted.
- Data flows: which component writes and which reads each file.
- Contracts: the six contracts between the components.
- Error codes: every error and warning code, what it means and what to do.
| Repository | Role | Card |
|---|---|---|
agentic/, in this repository |
Authoring acceleration, optional | agentic |
| living-doc-collector-gh | Collector: GitHub | collector-gh |
| living-doc-collector-ad | Collector: Azure DevOps, planned | collector-ad |
| living-doc-utilities | Shared library: contracts and parsers | utilities |
| living-doc-toolkit | Normalizer | toolkit |
| living-doc-generator-markdown | Generator: Markdown | generator-markdown |
| living-doc-generator-pdf | Generator: PDF, planned | generator-pdf |
Report a bug or propose a feature in GitHub Issues. Branches, pull requests, the page rules and the checks: CONTRIBUTING.md.
Licensed under the Apache License 2.0.