From f5fb0238f36cbb98de482c68842fc60c7ce959e2 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Sat, 10 Oct 2026 09:14:21 +0800 Subject: [PATCH 1/2] Decide the wiki structure, page names and languages (ADR-0001) English pages are generated and have no suffix; translations are named .da and .ms, written by hand in wiki/, reviewed and checked for staleness through a source hash. Add the ADR type to the registry. --- .../adr-0001-wiki-structure-and-languages.md | 99 +++++++++++++++++++ docs/artifact-registry.md | 6 +- 2 files changed, 103 insertions(+), 2 deletions(-) create mode 100644 docs/adr/adr-0001-wiki-structure-and-languages.md diff --git a/docs/adr/adr-0001-wiki-structure-and-languages.md b/docs/adr/adr-0001-wiki-structure-and-languages.md new file mode 100644 index 0000000..5aed546 --- /dev/null +++ b/docs/adr/adr-0001-wiki-structure-and-languages.md @@ -0,0 +1,99 @@ +# ADR-0001: Wiki structure, page names and languages + +## Metadata +| Key | Value | +| --- | --- | +| ID | ADR-0001 | +| CrossReference | [MIL-005], [BC-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-10 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending | + +Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. + +--- + +## Context + +MIL-005 puts the documentation on the Gitea wiki in English, Danish and +Bahasa Malaysia. Before translations are written, three things must be fixed, +because the generator, the publishing workflow and the translators all depend +on them: which pages exist, how a translated page is named, and which copy is +authoritative. + +Forces: + +- The Gitea wiki is a flat list of pages; a hyphen in a page name is shown as + a space, and a `/` in a name needs encoding in links and in the REST API. +- The English pages are generated from `README.md` and `guides/` + (`tools/build_wiki.py`) and published only by the workflow from `main` + (task 8). A translation must therefore live in this repository too, so it is + reviewed like any other change. +- A translation silently goes stale when the English page changes. Rule 8 of + `AGENTS.md` requires each translated page to name the English source it + follows, so staleness must be detectable without the network. +- The Business Case sets no deadline and the Product Owner language is + English, so English stays the single authoritative text. + +Options for the page name of a translation: + +1. **Suffix with a dot:** `Home` (English), `Home.da`, `Home.ms`. One flat + namespace, English has no suffix, and the files are `wiki/Home.da.md`. +2. **Folder per language:** `da/Home`, `ms/Home`. Mirrors the repository + layout but needs encoded links and an encoded API path. +3. **Suffix with a hyphen:** `Home-da`. Simple, but Gitea reads the hyphen as + a space, so the title shows as "Home da". + +Options for the source of truth of a translation: + +1. **Generated by machine on every change.** No stale pages, but no review by + a native reader and wording that changes between runs. +2. **Written once, kept in `wiki/`, reviewed, and checked for staleness.** + Reviewed wording is stable; staleness is flagged by a check. + +## Decision + +The wiki has five pages (Home, Onboarding, Credentials, Troubleshooting, +Capabilities). The English page has no suffix and is generated; a translation +is the page name plus `.da` or `.ms` (`Home.da`, `Credentials.ms`), written by +hand in `wiki/..md`, reviewed by a native reader, and published by +the same workflow. English is authoritative. + +Each translation starts with the comment +``, +so a check can report a translation whose English source has changed. Code +blocks, commands, file names and the workflow's error messages stay in +English. Terms are kept consistent through a term list (`docs/wiki-terms.md`, +created in MIL-005 task 4). + +## Consequences + +**Positive:** + +- One flat set of 15 pages that the existing generator and publisher handle + without a new code path. +- A stale translation is detectable offline from the recorded hash. +- Translations are reviewed and stable, and reach the wiki only by merge. + +**Negative:** + +- Dots in page names are not yet verified on this wiki; MIL-005 task 7 (#38) + must publish and open them. The fallback is `Home_da`, which changes only + the file names and links. +- A translation is not updated by itself; a person must re-translate when the + check reports it stale, so the translations can lag the English pages. +- The check, and the language switcher line at the top of each page, are + still to be built in task 4. + +## Affected Artifacts + +- [MIL-005] — closes task 1 (issue #32) and defines the naming that tasks 4 + and 5 follow. +- [BC-001] — the wiki in three languages is in its scope list. + +--- + +[MIL-005]: ../milestones/mil-005-wiki-and-translations.md +[BC-001]: ../business-case.md diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index 01a8d17..f0133c9 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -13,6 +13,7 @@ each document lives in *this* project and the next version to use. | MIL | Milestone / Gateway | docs/milestones/*.md | 006 | | RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 012 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | +| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0002 | ## Languages @@ -25,8 +26,9 @@ each document lives in *this* project and the next version to use. The PO language is English, so no PO-language translations are kept. The Gitea wiki (MIL-005) is the one exception: its pages are kept in English -(authoritative), Danish (`da`) and Bahasa Malaysia (`ms`). Each translated page -names the English source version it follows. +(authoritative), Danish (`da`) and Bahasa Malaysia (`ms`). A translation is named +`.` (`Home.da`) and names the English source it follows; see +`docs/adr/adr-0001-wiki-structure-and-languages.md`. | Artifact types | Register | Also kept as a PO-language file | | --- | --- | --- | From 20e02535bc654a3b0434a88160671e3b29735325 Mon Sep 17 00:00:00 2001 From: Jens Tirsvad Nielsen Date: Sat, 10 Oct 2026 09:14:22 +0800 Subject: [PATCH 2/2] Resolve pending commit link in ADR-0001 --- docs/adr/adr-0001-wiki-structure-and-languages.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/adr/adr-0001-wiki-structure-and-languages.md b/docs/adr/adr-0001-wiki-structure-and-languages.md index 5aed546..e527893 100644 --- a/docs/adr/adr-0001-wiki-structure-and-languages.md +++ b/docs/adr/adr-0001-wiki-structure-and-languages.md @@ -9,7 +9,7 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-10 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending | +| 2026-10-10 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | [f5fb023] | Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`. @@ -97,3 +97,4 @@ created in MIL-005 task 4). [MIL-005]: ../milestones/mil-005-wiki-and-translations.md [BC-001]: ../business-case.md +[f5fb023]: https://git.tirsystem.com/TirSystem/github-action/commit/f5fb0238f36cbb98de482c68842fc60c7ce959e2