snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Update Docs

Browse Source
This commit is contained in:
Raven Scott
2026-04-06 06:44:15 -04:00
parent 6d0d1b8049
commit f0fb05274b
21 changed files with 573 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CONTRIBUTING-DOCS.md
+19 -2
View File
@@ -1,6 +1,21 @@
# Contributing to Bare OS documentation
This repository ships documentation as **GitHub-flavored Markdown** (no static site generator in-tree). Changes are validated by **`npm run pretest`** (link checks, terminology rules, compatibility-matrix strings, roadmap row counts, **`verify-doc-tier1-count`** vs **`COREUTILS_COMMANDS`**, and more). Read [scripts/README.md](../scripts/README.md) for the full verifier list.
This repository ships documentation as **Markdown** with **GitHub-flavored** extensions (tables, fenced code, optional **GFM alerts**). There is **no** static site generator in-tree. The canonical git remote is **`https://git.ssh.surf/snxraven/bare-operating-system.git`**; prose should read well on **any** forge (some UIs render alerts as plain blockquotes — see [Admonitions](#admonitions-callouts) below).
Changes are validated by **`npm run pretest`** (link checks, terminology rules, compatibility-matrix strings, roadmap row counts, **`verify-doc-tier1-count`** vs **`COREUTILS_COMMANDS`**, and more). Read [scripts/README.md](../scripts/README.md) for the full verifier list.
**Optional Mermaid check:** [`.github/workflows/docs-mermaid-smoke.yml`](../.github/workflows/docs-mermaid-smoke.yml) runs **[`scripts/validate-mermaid-syntax.mjs`](../scripts/validate-mermaid-syntax.mjs)** on a schedule or **`workflow_dispatch`** (not a merge gate). Locally: **`BARE_OS_VALIDATE_MERMAID=1 node scripts/validate-mermaid-syntax.mjs`**.
---
## Good first documentation contributions
Low-risk ways to help without touching booter/kernel contracts:
- **Fix a broken relative link** — run **`npm run pretest`** ( **`verify-doc-links`** ) and follow the reported path.
- **Clarify onboarding** — [Get started](get-started.md), [Sitemap](sitemap.md), or [User manual ch.3](../users-manual/03-running-seeder-and-booter.md): keep version tables out of prose; **link** [compatibility matrix](reference/compatibility-matrix.md) and the [environment appendix](reference/environment-and-posix-appendix.md).
- **Add a prose fallback** next to a **Mermaid** diagram (terminal **`man`** and some forges omit diagram rendering); see [handbook preface](../handbook/00-preface.md).
- **Tier-1 `man` coverage** — if you add a **`/bin`** name, update **`packages/bare-os-coreutils/lib/commands.mjs`**, man JSON, and run **`npm run build -w bare-os-coreutils`** ( **`verify-man-coverage`** ).
---
@@ -8,6 +23,8 @@ This repository ships documentation as **GitHub-flavored Markdown** (no static s
| Audience | Tree | Role |
| --- | --- | --- |
| Zero-to-prompt | [docs/get-started.md](get-started.md) | Clone, prerequisites, two terminals, failure table |
| Doc orientation | [docs/sitemap.md](sitemap.md) | How trees connect |
| Short evergreen explainers | [docs/concepts/](concepts/README.md) | Two drives, boot, P2P, identity, POSIX — link out to handbook + reference |
| Operators / first run | [users-manual/](../users-manual/README.md) | Step-by-step: install, seeder/booter, shell, identity, troubleshooting |
| Narrative / architecture | [handbook/](../handbook/README.md) | Why the system is shaped this way; trust, protocol, runtime |
@@ -103,7 +120,7 @@ Avoid GitHub **`- [ ]` task lists** in normative documentation (they read as unf
If a diagram would need pixel-perfect branding or screenshots, add a **placeholder image** under [docs/images/](images/README.md) and reference it from the relevant page.
**Preview:** there is no Mermaid linter in **`pretest`**; use your editor or a Mermaid preview before pushing complex diagrams.
**Preview:** there is no Mermaid linter in **`pretest`**; use your editor or a Mermaid preview before pushing complex diagrams. For a full render smoke test, see **`BARE_OS_VALIDATE_MERMAID=1 node scripts/validate-mermaid-syntax.mjs`** and [`.github/workflows/docs-mermaid-smoke.yml`](../.github/workflows/docs-mermaid-smoke.yml).
---