69 lines
1.9 KiB
Markdown
69 lines
1.9 KiB
Markdown
# Docs Template
|
|
|
|
A starting point for Markdown-only documentation repos on the [Hellion Forge](https://gitea.hellion-forge.cloud/).
|
|
|
|
Use this for:
|
|
|
|
- specs and design documents
|
|
- architecture decision records (ADRs)
|
|
- runbooks and post-mortems
|
|
- internal wikis
|
|
|
|
This template is plain Markdown. If you want a rendered site, add MkDocs or Docusaurus on top — the structure here works as input for either.
|
|
|
|
---
|
|
|
|
## How to use this template
|
|
|
|
1. Click **"Use this template"** on the Forge.
|
|
2. Replace this README with one that describes your specific docs repo.
|
|
3. Drop content into the appropriate folders:
|
|
- `specs/` — feature specs, requirements, design proposals
|
|
- `decisions/` — ADRs (one file per decision, prefix `ADR-NNNN-`)
|
|
- `runbooks/` — operational guides, post-mortems, troubleshooting
|
|
|
|
If a folder doesn't fit your use case, delete it.
|
|
|
|
---
|
|
|
|
## Conventions
|
|
|
|
- **One topic per file.** No mega-docs. Cross-link instead.
|
|
- **Filename = title slug.** Lowercase-kebab-case (`backup-strategy.md`, not `Backup Strategy.md`).
|
|
- **Index files** at folder roots (`specs/INDEX.md` etc.) link to all files in the folder.
|
|
- **Frontmatter** for status / dates if you use a generator that needs it. Plain Markdown otherwise.
|
|
- **No screenshots in the repo unless they're load-bearing** — link to external assets if possible.
|
|
|
|
---
|
|
|
|
## ADR template
|
|
|
|
Architecture Decision Records: one file per decision, append-only.
|
|
|
|
```markdown
|
|
# ADR-0001: Title
|
|
|
|
**Date:** 2026-05-09
|
|
**Status:** accepted | superseded by ADR-NNNN | deprecated
|
|
|
|
## Context
|
|
|
|
What's the problem we're solving? Constraints, history.
|
|
|
|
## Decision
|
|
|
|
What did we decide. Concrete and short.
|
|
|
|
## Consequences
|
|
|
|
What changes because of this. Both positive and negative.
|
|
```
|
|
|
|
See `decisions/ADR-0001-example.md` for a worked example.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT — see `LICENSE`. (For docs that include third-party content, override accordingly.)
|