docs: adopt docs-template/ skeleton (architecture/usage/contributing/… - #11
Merged
Merged
Conversation
…troubleshooting + ADR) Closes Row-2 Phase 2 of the 2026-05-26 estate tech-debt audit chain for this repo. The 2026-05-26 documentation-debt audit (hyperpolymath/standards#197) flagged this repo as MEDIUM doc-debt: substantial top-level README but no docs/ tree. This PR seeds docs/ with the canonical 4-section + ADR skeleton from hyperpolymath/rsr-template-repo#75: - docs/architecture.adoc (system overview, components, invariants) - docs/usage.adoc (consumer perspective) - docs/contributing.adoc (developer perspective) - docs/troubleshooting.adoc (FAQ-style) - docs/decisions/0001-template.adoc (ADR template) Placeholders ({{PROJECT_NAME}}, etc.) have been substituted to this repo's actual values. The skeleton structure is canonical; the substantive content is owed to the maintainer. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
hyperpolymath added a commit
that referenced
this pull request
Jul 27, 2026
## What This repo was minted from the RSR template and got a docs skeleton (docs/architecture.adoc, docs/contributing.adoc, docs/usage.adoc, docs/troubleshooting.adoc, ADR 0001) adopted wholesale in #11, but the skeleton was never actually filled in — it still carried `<angle bracket>` placeholder tokens and generic boilerplate describing a built/tested software product (`just` recipes, an HTTP API, Rust source paths) that has never existed in this repo. `technical-notes` is, in fact, a documentation archive: short citable technical notes, individually deposited on Zenodo with a DOI (see README.md). No source code, build system, or test suite. This PR rewrites the process docs to say that, plainly and minimally, instead of describing a fictional product. ## Changes - `docs/architecture.adoc`, `docs/contributing.adoc`, `docs/usage.adoc`, `docs/troubleshooting.adoc`: replaced unfilled placeholders and fictional software-product content with a truthful description of the actual publishing/citation process. Fixed the stray `:revdate: 2026-MM-DD` placeholders. Dropped a dead link to a nonexistent `SECURITY.md`. - `ARCHITECTURE.md`, `GOVERNANCE.md`, `MAINTAINERS` (repo root): these were 100% unedited generic scaffold text (mentions `src/`, `tests/`, `scripts/`, `config/`, "public APIs", multi-maintainer RFC process) that never matched this repo. Rewritten to match reality: single maintainer, no software architecture. - `MAINTAINERS`, `.github/CODEOWNERS`, `.github/funding.yml`: these pointed at `@metadatastician`, the RSR template's literal default owner value, never swapped for this repo's real owner. Corrected to `@hyperpolymath`, which matches every commit author and existing SPDX `FileCopyrightText` in this repo. - `mise.toml`: trimmed from a full generic multi-language toolchain list (node/python/go/java/rust/…) down to what this repo actually needs — `git` and `typst` (for reproducing a note's rendered PDF). ## Not touched `flake.nix`, `.tool-versions` (not present), `.editorconfig`, `.gitattributes`, `.gitignore` — excluded per estate convention. `README.md`'s CC-BY-4.0 licence line for note *content* was left alone: it's consistent with `.zenodo.json` and is a separate, intentional licence from the MPL-2.0/CC-BY-SA-4.0 covering this repo's own tooling/process docs. ## Not applicable here No literal `{{...}}` mustache placeholders, `scripts/validate-template.sh`, `tests/e2e/template_instantiation_test.sh`, `justfile`, or `.zig` sources exist in this checkout, so those parts of the standard instantiation cure don't apply to this repo. ## Verification - `grep -rn '{{' .` (excluding GitHub Actions `${{ }}` expressions): clean. - `grep -rn 'metadatastician'`: clean. - `grep -rn 'MM-DD'`: clean. - Remaining `<...>` placeholders in docs: only one intentional notational use (`zenodo.<version>` describing the DOI *format*, not an unfilled field). - All three `.github/workflows/*.yml` files parse as valid YAML (`python3 -c "import yaml; yaml.safe_load(...)"`), each with at least one job — unchanged by this PR, verified as a regression check. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
…troubleshooting + ADR)
Closes Row-2 Phase 2 of the 2026-05-26 estate tech-debt audit chain for this repo. The 2026-05-26 documentation-debt audit (hyperpolymath/standards#197) flagged this repo as MEDIUM doc-debt: substantial top-level README but no docs/ tree.
This PR seeds docs/ with the canonical 4-section + ADR skeleton from hyperpolymath/rsr-template-repo#75:
Placeholders ({{PROJECT_NAME}}, etc.) have been substituted to this repo's actual values. The skeleton structure is canonical; the substantive content is owed to the maintainer.