[markbac]

Moves the glossary in from technical-documentation/docs/glossary and site-web-content-src/Glossary/src as one py-doc document: an index page, one page per letter (a.md to z.md) and numbers.md for terms that start with a number or symbol. There are 1,060 terms, each a ## heading with its own anchor. py-doc build glossary makes one PDF and one Word file of the whole glossary.

The two sources

They are the same glossary in two shapes. technical-documentation has it as six letter-group pages (1,081 terms); site-web-content-src has it as one file per term (1,093 files), which tarf.co.uk served as one page per term under /Glossary/. 778 shared entries are identical once whitespace is normalised; the other 273 differ only by typo fixes, line wrapping and image references.

• Only in technical-documentation (added later): ADR, BFF, CBOR, DTLS, DoD, DoR, FOTA, HLD, LwM2M, MCU, MPU, RoT, Root of Trust, SDS, SE, Secure Element, SOLID Principles, STRIDE Threat Model, TOGAF, TrustZone. A few more are spelling fixes of site-web-content-src names (authorriative Answer, dotNET, GBE - GE, Tcl-tk, CUE ).
• Only in site-web-content-src: G.729 (an empty file), Csharp (a duplicate of C#), the per-letter index pages, and eight .tmp AsciiDoc leftovers.

Provenance

New file	From
content/glossary/index.md	technical-documentation/docs/glossary/index.md, rewritten
content/glossary/<letter>.md (a to z)	That letter's section of technical-documentation/docs/glossary/{a-c,d-f,g-k,l-n,o-r,s-z}.md, and site-web-content-src/Glossary/src/<letter>/*.md. µ-law (src/μ/) is now "Mu-law" in m.md
content/glossary/numbers.md	The "#" section of .../docs/glossary/s-z.md, and .../Glossary/src/{1,5,8}/*.md
content/glossary/redirects.tsv	Built from web-content/Glossary/**/index.html (tarf URLs) and the old headings (technical-documentation anchors)
py-doc.yml	documents.glossary.sources lists the seven files in order

What changed in the text

• Every entry is rewritten, not copied. Almost all the longer entries were Wikipedia text, verbatim or lightly edited. The short process entries came from Construx's CxOne glossary and the Agile Alliance glossary. A few came from Openreach, a UK broadband information site (WBC, WBMC, WBCC), US Army material (WIN-T) and a blog (risk-reward matrix). No sentence is kept verbatim.
• Trimmed to a glossary: 104k words became about 34k. Each entry is a definition (acronyms give their expansion in bold first), a sentence or two of detail where it helps, then "See also" links. No entry is over 110 words.
• Duplicates merged: one entry each for things like Acceptance Test/Testing, Unit Test/Testing, Smoke Test/testing, Agile/Agile development, Waterfall/Waterfall Lifecycle, Spiral Model/Lifecycle, RAD/Rapid Application Development, IDE, IEEE, ISO and UML. Short alias entries ("See [IDE]") stay where an old URL points at them.
• Errors fixed: FXO and FXS were swapped; MNC described the BNC connector (now the Mobile Network Code); CLF described the SLF; UTF-16 described UTF-32; IPv4 and IPv6 had each other's expansions; NBAP had NB-IoT text appended (NB-IoT is now its own entry).
• Renamed: Complier → Compiler, Sematic Versioning → Semantic Versioning, Sprial Model → Spiral Model, Date Warehouse → Data Warehouse, Deplhi → Delphi, Risk Reward Matric → Risk Reward Matrix, EEE 802.1Qay → IEEE 802.1Qay, Artifact → Artefact, Expert Judgment → Expert Judgement, Modeling → Modelling, Python (2.x & 3.x) → Python, IOS cisco OS → IOS, 100 Mbps---Fast Ethernet → 100 Mbps (Fast Ethernet), µ-law → Mu-law.
• Cross-section links removed: the newer entries linked to ../guidelines/GU-0xx and ../guides/architecture-handbook/.... Those sections are moving in parallel, so I left the links out (see the questions below).
• British English throughout; strict lint is clean. Four official US-spelled names (International Organization for Standardization, Unified Modeling Language, GNU General Public License, Program Evaluation and Review Technique) are wrapped in <!-- vale PyDoc.Spelling = NO --> switches.

Encyclopaedic material left out

Most of it was Wikipedia, so it is better linked than kept. The entries that lost the most were Linux (distribution list), NGN, Mediation, VHDL, SS7 (national variants), Softswitch, RRC (state machine), FIPS 140-2 (security levels), WIN-T (increments), Capability Maturity Model (key process areas), Unicode, Jitter buffer, Latency, packet sniffing, NoSQL, Risk-Reward Matrix, SystemX (concentrator internals) and the codecs (bit-rate tables). Code samples went too: the BNF postal address grammar, an SGML DTD, a WSDL document, the SemVer grammar and the Gherkin examples. If any of these should live on as a primer or reference page, they would be written fresh there.

Dropped, and why

Term	Why
Best Practice Description, CAM Item, Construx Knowledge Area, Corrective Activity Management, Evaluation, Lite, Link, Material, Reference	Construx CxOne product terms with no meaning outside CxOne. Their URLs go to Best Practice, Item, Software Engineering Body of Knowledge, or the letter page
L2S, LAS, LPS, MAG, MAS, MPS, Rainbow	A former employer's internal device-role codes and system name ("M2F", "Remedy 7.6"): not general terms, and arguably internal
LTE and Mobile Internet, Mobile Networks 2G/3G	A picture only, no text. URLs go to LTE (4G) and UMTS
G.729	An empty file. URL goes to Audio Codecs
"The first example has two steps", "The second example has three steps"	Gherkin examples that the old conversion split into terms. URLs go to Gherkin
International Organization for Standardization, Unified Modeling Language	Alias stubs merged into ISO and UML
Every image (about 230 files, 3 duplicate groups, 6 broken references)	Almost all third-party: Wikimedia diagrams, BT and Openreach drawings, vendor and lecture slides, TechRepublic, finder.com. The rest looked like a former employer's network diagrams. Eight are redrawn as Mermaid (Dot1Q trunking, DTE/DCE, duplex, multicast, network topologies, protocol stack, TLS handshake, V model) and two as tables (MOS scale, UDP header), so there is no images/ folder

Redirects

content/glossary/redirects.tsv has 2,182 rows (old_url, redirect_from, redirect_to, note). I have not changed mkdocs.yml.

• tarf.co.uk: 1,094 rows, one for every built page under /Glossary/, such as https://tarf.co.uk/Glossary/a/AES/ → glossary/a.md#aes. The redirect_from and redirect_to columns are already in the form mkdocs-redirects takes for redirect_maps in site/mkdocs.tarf.yml. Note that the old paths use a capital G.
• markbac.github.io/technical-documentation/glossary/: 1,088 rows. The index and the six old group pages, plus every old anchor mapped to its letter page. The anchors themselves are unchanged, because the new ids use the same MkDocs slugs, except for renamed or dropped terms. These redirects belong in the technical-documentation repository, not here.
• New URLs: https://markbac.github.io/glossary/a/#aes and https://tarf.co.uk/glossary/a/#aes.

Checks

• py-doc lint content/glossary --strict (built-in rules and Vale 3.15.2): 0 warnings or errors.
• py-doc build glossary: build/glossary.docx and build/glossary.pdf (176 pages, a chapter per letter).
• py-doc site build: both sites build. A script checked every anchor link in the built glossary pages: 1,060 term headings and 5,263 links on each site, 0 broken.

py-doc problems found (not fixed here)

1. CI will fail on any document with a diagram. diagrams/render.py _tools_revision() reads every entry of py_doc/diagrams/tools/. pip's __pycache__ folder is one of them, so the build fails with PermissionError on Windows and IsADirectoryError on Linux. I deleted that folder in my local venv to build. The glossary has eight Mermaid diagrams, so this PR's "Word and PDF files" step will fail until py-doc skips non-files.
2. Links between a document's own files are dead in Word and PDF. d.md#dns stays an external link, and the glossary has 1,530 links between letter pages. The sites rewrite them correctly; same-file links work everywhere. py-doc should turn other-source.md#id into #id when it combines the sources.
3. Site pages drop explicit heading ids ({#id}), and MkDocs re-slugs them. So the content uses MkDocs' slug as every anchor, with an explicit id only where pandoc's own would differ: 36 headings, such as ASN.1 {#asn1} and C# {#c_2}.
4. toc_depth in front matter does not shorten the PDF's contents, which list every term .

Questions for Mark

1. Were any of the dropped pictures your own drawings that you want back, such as the risk-reward matrix, the task board photo, or the EAD, EoFTTC and SoGEA diagrams?
2. Keep the CxOne-flavoured process and role terms (Construction Lead, Planning and Tracking Lead, Miniature Milestone and so on), or drop them?
3. Keep the UK wholesale product terms (WBC, WBMC, WBCC, IPSC, MBORC, MPF, SMPF, SoGEA, EAD, WLR) and the address data terms (PAF, MRS, NYB, PNT, DNB, IDQ)? They date quickly.
4. Should the entries for ADR, HLD, DoD, DoR, SDS, SOLID, STRIDE, FOTA and Root of Trust link to the guideline and handbook pages again once those sections have merged?
5. Wire the tarf redirects into site/mkdocs.tarf.yml in a follow-up? That adds 1,094 small redirect pages.

🤖 Generated with Claude Code