From 25e5a4b739d38741f467ba55d083c965dfe57a15 Mon Sep 17 00:00:00 2001 From: msa46 Date: Tue, 11 Aug 2026 18:32:36 +0200 Subject: [PATCH] docs: design useful guides publication --- ...-08-11-useful-guides-publication-design.md | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-11-useful-guides-publication-design.md diff --git a/docs/superpowers/specs/2026-08-11-useful-guides-publication-design.md b/docs/superpowers/specs/2026-08-11-useful-guides-publication-design.md new file mode 100644 index 0000000..a7be57c --- /dev/null +++ b/docs/superpowers/specs/2026-08-11-useful-guides-publication-design.md @@ -0,0 +1,72 @@ +# Useful Guides Publication Design + +## Goal + +Publish the practical Useful Guides retained in the 2026-08-02 `wiki.msvincognito.nl` snapshot as first-class pages in the current Starlight wiki. Publish all four guide topics without adding historical-warning callouts, and include the newer laptop recommendations that are absent from the current migrated laptop page. + +## Scope + +The published Useful Information section will contain: + +- Laptop Buying Advice +- Housing Guide +- Linux Tricks +- Surviving DACS + +The existing Laptop Buying Advice destination will be updated in place. The other three guides will be added under `src/content/docs/useful-information/` and exposed through the Useful Information landing page and manual sidebar. + +Course content, the original DokuWiki migration, and unrelated Useful Information pages are outside this change. + +## Sources and destinations + +| Archived source | Published destination | +| --- | --- | +| `to-be-studied/live-wiki/2026-08-02/useful-guides/laptop-buying-advice.md` | `src/content/docs/useful-information/laptop-buying-advice.md` | +| `to-be-studied/live-wiki/2026-08-02/useful-guides/housing-guide.md` | `src/content/docs/useful-information/housing-guide.md` | +| `to-be-studied/live-wiki/2026-08-02/useful-guides/linux-tricks.md` | `src/content/docs/useful-information/linux-tricks.md` | +| `to-be-studied/live-wiki/2026-08-02/useful-guides/survivingdacs.md` | `src/content/docs/useful-information/surviving-dacs.md` | + +Each newly published destination will be declared in `docs/supplemental-content.json` with its original public source URL and a `useful-guide-recovery` category. The laptop page remains covered by the original migration manifest because its destination already exists there. + +## Content treatment + +Use a faithful, maintainable migration rather than a verbatim scrape or a full rewrite: + +- Preserve the guides' practical substance, contributor voice, headings, lists, and useful external references. +- Convert captured HTML remnants and snapshot-specific formatting to ordinary Starlight Markdown. +- Correct obvious spelling, grammar, and formatting defects without changing meaning. +- Do not add historical-information or dated-warning callouts. +- Retain source-provided dates only where they identify authorship or the guide's own revision context; do not turn them into warnings. +- Remove dead links, instructions that expose obsolete credential-handling practices, and recommendations that create avoidable legal or safety risk. Rewrite the surrounding sentence when needed so the page remains coherent. +- Do not invent current facts or silently claim that time-sensitive prices, services, housing practices, or university systems have been reverified. + +The Laptop Buying Advice page will lead with the newer source recommendations: + +- at least 16 GB RAM; +- at least 512 GB SSD storage; +- a mid-range Intel Core i5-class or equivalent processor; +- M-series Mac compatibility, with possible course-specific compatibility considerations; +- an Nvidia GPU recommendation for Data Science and AI workloads that use CUDA. + +The older price-tier material may remain as general budget context, but language that presents old configurations or prices as current purchasing targets will be revised or removed. + +## Navigation and discovery + +Update `src/content/docs/useful-information/index.md` to introduce the practical guides and link all four of them alongside the existing location and IT pages. Add the three new routes to the Useful Information group in `src/config/sidebar.mjs`, keeping related guides adjacent. + +No redirects or new top-level navigation group are needed. Existing `/useful-information/` routes remain unchanged. + +## Validation + +Automated coverage will verify: + +- all three new destination files exist and are registered as supplemental content; +- the Useful Information landing page links all four practical guides; +- the sidebar exposes the three new routes; +- the laptop page contains the newer minimum RAM and storage recommendations, M-series guidance, and Nvidia/CUDA guidance; +- the content audit accepts the additional supplemental destinations; +- the full project verification succeeds, including Astro checks, tests, build, content audit, and internal-link validation. + +## Success criteria + +Visitors can discover and read all four practical guides from the Useful Information section of the new wiki. The laptop guide contains the newer recommendations from the GitHub-era wiki. The pages render as native Starlight content, contain no added historical-warning callouts, and pass the repository's complete verification workflow.