Skip to content

Commit d2bb45b

Browse files
fvarruiclaude
andcommitted
Close the docs-site MiniSpec note
The decision (Docusaurus in docs/, published from main, no versioned docs) is recorded as ADR-005; the rest is already in CLAUDE.md, the conventions and the architecture. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 7b24080 commit d2bb45b

2 files changed

Lines changed: 20 additions & 31 deletions

File tree

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# ADR-005: User documentation as a Docusaurus site on GitHub Pages
2+
3+
## Decision
4+
5+
The user documentation is a Docusaurus site in `docs/` (pages in `docs/content/`), published to GitHub Pages (https://javapackager.github.io/JavaPackager/) from `main`, with no versioned docs. `README.md` is only a quick start that links to it.
6+
7+
## Motivation
8+
9+
- The README had grown into a 426-line manual, hard to navigate and partly outdated; the pages in `docs/` were scattered and had wrong defaults.
10+
- A site gives navigation, search-friendly pages and a place for guides, without leaving the repo: docs are reviewed and changed with the code.
11+
- Publishing from `main` keeps the site in step with the latest release on Maven Central; publishing from `devel` would document unreleased features.
12+
- Versioned docs (one copy per release) were rejected: too much upkeep for a project with one supported major. Differences between versions go in the release notes and the upgrading page.
13+
- `docs/content/` instead of Docusaurus' default `docs/docs/`, to avoid the confusing repeated name.
14+
15+
## Consequences
16+
17+
- Docs are changed in `devel` with the code, and reach the site when `devel` is merged into `main` (a fix to the docs alone can be merged earlier).
18+
- `.github/workflows/docs.yml` builds the site on `devel` and pull requests (broken links fail the build) and deploys it from `main`.
19+
- A new property or behaviour is documented in `docs/content/` (conventions), checked against the code, with Maven and Gradle syntax.
20+
- The site documents only the latest release; users of older versions rely on the release notes.

‎.minispec/features/docs-site.md‎

Lines changed: 0 additions & 31 deletions
This file was deleted.

0 commit comments

Comments
 (0)