Repository navigation
Phase 1: move the remaining sections in, one commit per section - #6
Merged
Merged
Conversation
PR #4 moved the primers in but did not add them to site.documents, so neither site showed them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ngineeringProcess New: project vision, architecture vision and principles, crosscutting concerns, software design specification, traceability matrix, test plan, decision log, meeting minutes, lessons learned, release plan, risk register, SBOM, systems engineering management plan, team working agreement, technical debt register, NFR scenario. Each follows the section's pattern: an introduction, then the template in a fence. The other ten docs-WoW templates were already covered (ADR, RFC, the canvases, postmortem, experiment record, interface specification, architecture document, requirements). The index groups the templates by project stage. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… pages, and publish the section - EG-001 to EG-026, core rules, combined checklists, agent rules, organisation adoption, personal projects, the business principles overview and the principles catalogue. - File names drop the eg-NNN- prefix; each page gets an H1 with its ID. Links to templates-reference now point to the Templates section. - EG-014 gains VCS-15 (imperative subject under 72 characters, a body that says why), the one rule GU-014 had that EG-014 did not. GU-015's PR format was already covered by EG-015 and the pull request template. - EngineeringProcess's AGENTS.md becomes a template, since the guidelines tell readers to copy it. - Seven sentences over 30 words split to clear the lint warnings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, and publish the section C coding standard, MISRA C, Python for supporting tools, software architecture principles, API design, unique identifiers, LwM2M objects, IoT device architecture principles, battery budgeting, constrained binary payloads, offline storage, and serialisation and factory test. - Word-based file names and shorter sentence-case titles; the old GU numbers are dropped. - GU-009 is technical-documentation's single-file C standard. wip's 11-part split is not published: it draws on an employer's internal standards. - en-GB spelling in prose (not in code), long sentences split, heading levels fixed so each standard is one chapter in Word and PDF. - Mermaid labels with brackets quoted, and semicolons removed from sequence messages, so the diagrams render. \text in maths becomes \mathrm, because py-doc's PDF template has no amsmath. - Six links point at guides that the guides commit adds. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ents and the docs-WoW team guides, and publish the section - Six guides from technical-documentation, each in its own folder with numbered chapters: C4 modelling, cyber security, IoT endpoint and gateway architecture, IoT fleet operations, HIL and automated testing, scaling architecture. The architecture handbook moves separately. - Single-page guides from the how-to GUs: ADRs and RFCs (GU-005 and GU-006 together, their templates now pointing to the Templates section), software design specification, high-level design, architecture review board, agile requirements, defects and debugging, and code review (GU-011 plus docs-WoW's roles section; its PR template points to the Templates section). - Git: GU-013 with docs-WoW's branching strategies and version control chapters. docs-WoW's other Git guide (git.md) covered the same ground as GU-013 and is not moved. - Ways of working: docs-WoW's eight team guides as one guide. - Clean-ups: emoji out of headings, :::mermaid blocks fenced, heading colons and skipped levels fixed, en-GB spelling in prose, 70 long sentences split, Mermaid labels quoted, C4-PlantUML from PlantUML's standard library, the C4 tooling section now uses py-doc c4. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d publish the section - The eight chapters keep their numbers; titles in sentence case. - Chapter 3 gains a section on message queues and publish-subscribe, the one topic in site-web-content-src's older handbook that this one did not cover. The rest of that handbook is the earlier version of the same eight chapters and is not moved. - C4-PlantUML includes use PlantUML's standard library; long sentences split; en-GB spelling. Also across the sections moved so far: - Links and mentions that still named a GU number now use the title of the page that replaced it, and links to the Git guide point at its folder. - Mermaid cylinder shapes ([( )]) that an earlier clean-up had turned into boxes are restored. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…section and the interactive chart - The section: the methodology (from overview.md) as the section page, the four quadrant pages and the directory of all 77 entries. It builds as Word and PDF like the other sections. - The interactive SVG chart (ADR-003: vanilla JavaScript, no outside dependencies) is HTML and script, so it is a site page of its own, site/docs/radar-chart/, listed under site.pages. - The chart's links went to technical-documentation's layout (GU files, primers by area, the old guide folders). Each now points at the page that replaced it, as a site URL; all 47 resolve. - site-web-content-src's TechRadar app (Next.js) is the older radar and is not moved. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…appendices, and publish the section - The book as written: preface, acknowledgements, introduction, and Parts One to Three with their 29 chapters, each part in its own folder and each chapter numbered. - Firmitas 2's Appendix was empty, so it takes the first edition's Appendices A to G, and the first edition's Sections V (practice across disciplines) and VI (quality, regulation and assurance) as Appendices H and I. The second edition has no chapters on those subjects yet. - Left behind: the rest of the first edition (rewritten as Firmitas 2), Firmitas_Framework.md (the first edition in one file), cornerstone*.md (the framework's earlier name), the draft essays (the second becomes a blog post) and plan.md (a work plan, not for publication). - Mechanical fixes only, since this is the author's own prose: the manuscript header in Chapter 2, heading levels, four spellings, and the cone of uncertainty image, which had not been copied. The style warnings stay: 779 sentences over 30 words, three 'in order to', one heading ending in '!' (a book title). - The front page carries the CC BY-NC-ND 4.0 licence notice and the cover. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… essay, as written - Networking and home lab series: the 30 posts from wip/, dated 25 April 2025 in the order wip/list.md planned, each marked with its part number, plus a series page listing them (two planned posts were never written and are listed as such). - Home lab: the four tech_blog posts, 11 March 2025. The real internal addresses and domain are replaced with documentation values (192.0.2.x, home.example). - Architecture flashcards and the embedded architecture process mind map, 18 February 2025. - An Approach to Engineering Leadership and Delivery, 28 December 2025, leading into Firmitas. - The software design specification post takes the longer version of its text (SDS-wip.md), under the same date and slug. - Mechanical fixes only: titles as H1, heading levels, the excerpt marker, a post that was wrapped in a code fence, five spellings, a shorter slug. Style warnings stay (32 long sentences). - Not moved: planning notes (the docs-as-code series outline, the blog idea lists). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CBOR, CoAP, LwM2M, NB-IoT and cellular, certificates and keys, RTOS internals, SysVars, MISRA C, static analysis, Git internals, and docs, diagrams and architecture as code. Moved as written: mechanical fixes only (one hardware reference removed from the NB-IoT page, heading levels, spelling), so their 264 long sentences remain as warnings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The six letter-group pages (a-c to s-z) become 26 letter pages, numbers.md (5G, 802.11 and the other terms that start with a digit) and symbols.md (.NET). Each term is now a ## heading on its letter's page, with the same anchor as before. - Every link between terms follows its term: 1,336 cross-page and 691 same-page links checked, none unresolved. - redirects.tsv: the 1,135 rows that pointed at a group page now point at the term's letter page; six new rows send the old group pages to the glossary index. - The index lists the pages with their term counts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The glossary move (#3) left out its 237 images. They are back: 241 references in 205 terms, 235 image files in content/glossary/images/, from technical-documentation's glossary. Each sits after its term's definition, with the term as alt text and a caption. Terms that were renamed or merged get their images through the redirect map. Not restored: the NBAP entry's hotlinked everythingrf.com picture (external, not a file in the repository), and the images of L2S and MPS, terms the glossary dropped. Most of these images are third-party (Wikimedia, BT and Openreach, vendor and lecture slides), restored on the owner's instruction. Co-Authored-By: Claude Opus 5.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 free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Phase 1 of consolidating the documentation repositories: every section that was still a placeholder moves in, apart from Reference (left out on purpose). One commit per section. Each section is listed in
site.documents, so it is published on both sites once this merges.What moved, and from where
Where a GU document went: checklists GU-001 to GU-004 and GU-018 were already templates. GU-014 and GU-015 folded into EG-014 and EG-015 (one new rule, VCS-15). GU-010 is covered by EG-004 and the docs-as-code primer. GU-005 and GU-006 became one guide. The rest became standards or guides.
Decisions to know about
git.md: GU-013 covers the same ground.Firmitas_Framework.mdandcornerstone*.md: superseded by Firmitas 2.docs_as_code.mdoutline,0-blogs-list.md,Notes.md,Guide.md).plan.md.home.examplein place of the real ones.Clean-ups made to the moved reference text
The guidelines, standards, guides, handbook and radar pass
py-doc lint --strictwith 0 warnings. To get there::::mermaidblocks fenced. C4-PlantUML now comes from PlantUML's standard library.\textin maths became\mathrm, because py-doc's PDF template does not load amsmath. That template is worth a py-doc issue.Glossary changes
content/glossary/images/(27 MB). Most are third-party (Wikimedia, BT and Openreach, vendor slides), and were restored as asked. Not restored: one hotlinked external image, and the images of L2S and MPS, terms the glossary dropped.Checks
py-doc lint --strict: 0 warnings for guidelines, standards, guides (apart from the Deep dives), handbook, radar and templates. Firmitas and the blog have only the style warnings described above, plus heading warnings in six posts that were already published.py-doc buildfor every section: each one writes its DOCX and PDF.py-doc site build: both targets build. Section pages, the radar chart and the new posts are generated. All 47 chart links resolve.content/at once fails on Windows only: py-doc passes every file to Vale on one command line, which is too long. CI runs on Linux.🤖 Generated with Claude Code