[Doc Feature] Migrate the technical documentation from DOCX to AsciiDoc (chapter-per-file, readable on GitHub, PDF via make docs)

[RomanAlexandroff]

Summary

The project's technical documentation currently lives in a single Word file: docs/Technical Documentation.docx (~70 pages, ~23,000 words, 331 KB). The content is comprehensive and valuable, but the container works against it:

• GitHub cannot render .docx — visitors only get a download button. On a phone, the documentation is effectively unreachable.
• GitHub repository search cannot look inside a binary file, so searching the repo for "rollback" or "manifest" will never surface the documentation.
• The file cannot be diffed or reviewed piece-by-piece in a pull request, so documentation changes cannot travel in the same commit as the code changes they describe.
• The table of contents is typed by hand, with hand-typed page numbers, and has already drifted from the actual content.
• Updating a large exported document has high friction, which is part of why gaps like [Doc Issue] Missing documentation on the Automatic Firmware OTA Update Pipeline #46 exist.

Decision (final): migrate the documentation to AsciiDoc, split into one .adoc file per chapter inside docs/tech_documentation/, with a docs/tech_documentation/README.md index replacing the hand-made table of contents, all images in docs/tech_documentation/media/, and a make docs target that builds a polished single-file PDF via asciidoctor-pdf.

This keeps the documentation in the repository next to the code, makes every chapter readable directly in the browser (GitHub renders .adoc natively), makes the content searchable and reviewable, and still produces a beautiful standalone PDF for handing to non-GitHub readers (Bocal, staff).

Goals

• Every chapter is readable on github.com in the browser, with no download step, including on mobile.
• Documentation content is found by GitHub repository search.
• Documentation changes are made in normal pull requests, ideally in the same commit as the related code change.
• The table of contents is generated, not maintained by hand, and can never drift again.
• make docs produces a single PDF of the whole documentation.
• The root README.md links directly to the documentation index (one click from the front page).

Non-goals (follow-up issues, not this one)

• No content rewriting. This migration moves text as-is. Typo fixes, copy-editing, and rewriting stay out of scope so the parity review stays easy.
• No writing of missing chapters. The chapters marked //TO-DO in the current document (Hardware description, Circuit diagrams and schematics, Description of the program constants, Power management, Safety considerations, The Don'ts of changing the program, Suggestions for dealing with confidential information) are migrated as stubs and get their own issues.
• The OTA release-pipeline chapter stays tracked in [Doc Issue] Missing documentation on the Automatic Firmware OTA Update Pipeline #46. This migration only removes the friction that made [Doc Issue] Missing documentation on the Automatic Firmware OTA Update Pipeline #46 expensive to fix.

Target structure

in the /docs folder:

tech_documentation/
├── README.md                          <- index: linked chapter list (replaces the hand TOC)
├── book.adoc                          <- master file for the PDF build only (uses include::)
├── 01-vocabulary-of-terms.adoc
├── 02-about-the-project.adoc
├── 03-contractors-requirements.adoc
├── 04-program-run-overview.adoc       <- "General description of the program run"
├── 05-program-run-step-by-step.adoc
├── 06-how-to-build-the-sign.adoc
├── 07-development-environment.adoc    <- "Getting ready to maintain and develop the project"
├── 08-cloud-pull-ota-updates.adoc
├── 09-uploading-compiled-binary.adoc
├── 10-firmware-rollback.adoc
├── 11-hardware-maintenance.adoc
├── 12-functions-reference.adoc
├── 13-architectural-decisions.adoc
├── 14-intra-api.adoc                  <- "How to get exams info from Intra" + example responses
├── 15-exam-simulation.adoc
├── 16-create-your-own-graphics.adoc
├── 17-how-to-draw-on-the-display.adoc
├── 18-time-keeping.adoc
├── 19-service-messages.adoc
├── 20-libraries.adoc
├── 21-known-bugs-and-fixes.adoc       <- "Bugs and suggestions how to fix them"
├── 22-reporting-and-suggestions.adoc  <- "New bugs and future development suggestions"
├── 23-confidential-information.adoc   <- stub (//TO-DO in the original)
├── 24-external-sources.adoc
└── media/                             <- all images, with meaningful file names

Naming rules: lowercase, digits, hyphens, no spaces in file names (the space in Technical Documentation.docx breaks URLs and shell commands — let's not repeat it). The numeric prefix keeps the reading order visible in the file listing.

Every chapter file starts with a small standard header, for example:

= Architectural Decisions Explained
:imagesdir: media
:sectnums:
:toc: auto

(chapter text)

tech_documentation/book.adoc is used only by the PDF build. It sets :doctype: book, the title page attributes, and include:: directives listing all chapters in order. Note for readers at the top of book.adoc: GitHub's web view does not process include::, so this file looks empty-ish on GitHub — that is expected; browse via tech_documentation/README.md instead. This is exactly why the readable structure is chapter-per-file plus an index, not one master file.

Migration steps

1. Prepare

• Create the docs/tech_documentation/media/ folder.
• Extract the 9 embedded images from the .docx (a .docx is a ZIP: the images are in word/media/) and give them meaningful names (front-view.png, display-pins.png, ... — pick names while placing them into chapters).
• Install the tools locally: pandoc for the conversion, asciidoctor and asciidoctor-pdf (Ruby gems) for rendering.

2. Convert

• Run a first-pass conversion with pandoc (pandoc "Technical Documentation.docx" -t asciidoc), but do not trust it blindly — see "Known conversion gotchas" below. The chapter titles will not come out as headings automatically and must be fixed by hand or by a small mapping script.
• Split the converted text into the chapter files listed above.
• Restore the heading structure in each chapter: original chapter titles become = titles, the document's Heading 1 / Heading 2 paragraphs become == / === sections.
• Re-insert the images at their original positions with image:: macros and captions.
• Convert the Word tables (there are 10) into AsciiDoc tables — except the old table of contents table, which is dropped entirely and replaced by docs/tech_documentation/README.md.
• Put the Intra server example responses (token response, exam information response) into [source,json] code blocks.
• Turn "do not do X" style warnings (the setup() order warnings, the "ota.h include must stay at the bottom" note, the Don'ts) into AsciiDoc admonition blocks (WARNING:, IMPORTANT:, NOTE:) — this is the kind of formatting upgrade the migration is for.
• Where the text says "read chapter X first", make it an actual cross-reference link to that chapter file.
• Remove all references to page numbers (they stop existing); link to chapters or sections instead.
• Keep the honest //TO-DO markers, but convert them into a visible NOTE: This chapter is a stub — see issue #NN. line, and open one small issue per missing chapter.

3. Index and entry points

• Write docs/tech_documentation/README.md: a short intro line plus the linked list of all chapters with a one-line description each. This is the new table of contents. No page numbers, ever again.
• Link the index prominently from the root README.md (top of the page, not only in a lower section), with link text that says what it is, e.g. "Full technical documentation — architecture, build guide, function reference".
• Check that all old references to the .docx (README mentions, issues, wiki, anywhere) now point to docs/tech_documentation/README.md.

4. PDF build

• Create docs/tech_documentation/book.adoc (master file with include:: lines in reading order, :doctype: book, title page, :toc:).
• Add a docs target to the Makefile, in the spirit of the existing release targets:

docs:
	asciidoctor-pdf docs/tech_documentation/book.adoc -o build/Technical_Documentation.pdf

• Do not commit the generated PDF to the repository; it is a build artifact. (Optional follow-up: attach it to GitHub Releases from the release flow.)
• Optional: a small CI job that runs make docs on pull requests touching docs/tech_documentation/, so a broken include or malformed table fails loudly instead of silently.

5. Verify and clean up

• Parity review: open the old .docx and the new chapters side by side, chapter by chapter, and confirm nothing was lost. (Suggested method: tick off chapters against the structure list above.)
• Open every chapter on github.com in a desktop browser and on a phone — confirm headings, images, tables, and admonitions render.
• Run make docs and read through the PDF once — title page, chapter order, images, page breaks.
• Use GitHub repo search for a few terms that only exist in the documentation (e.g. "pathfinder", "brown-out", "partial update window") and confirm they now produce results.
• Remove docs/Technical Documentation.docx from the branch. Git history keeps it forever, so nothing is lost; the working tree should have exactly one source of truth.

Known conversion gotchas (found by inspecting the actual file — read before starting)

1. Chapter titles will not convert to headings automatically. The document was written in a Czech-language Word, and the chapter titles use the Title style (internal id Titul). Converters map heading styles by name and do not treat Title as a heading, so a naive pandoc run produces a flat wall of text. All ~26 chapter titles must be promoted to = titles by hand or by a small script. The Heading 1 / Heading 2 paragraphs (internal ids Nadpis1 / Nadpis2) also need checking — do not assume the converter got them.
2. Two drawings will be silently lost. The screen mock-ups "OTA UPDATE WAS CANCELED" and "TELEGRAM BOT ERROR" are drawn as Word shapes with text boxes, and converters drop text-box content. They must be recreated as PNG images in docs/media/. Best option: render them from the actual bitmaps in bitmap_library.h, which makes the documentation pictures pixel-accurate to the device for free.
3. The decorative cover page does not survive. That is fine — the PDF gets a generated title page from book.adoc, and the GitHub index does not need one. Do not spend time recreating it.
4. Some shape text appears twice in converted output (Word stores drawings in a main + fallback form). Delete the duplicates during cleanup.
5. Bold/italic may come out fragmented or misplaced (Word splits formatting into many small runs). Expect to re-apply emphasis by eye in some paragraphs rather than trusting the converter.
6. Typographic quotes („ ", ‚ ') from the Word autocorrect can be kept or normalized — just be consistent. Not a blocker.
7. GitHub does not process include:: when rendering .adoc files in the web view. This is a display limitation of github.com, not of AsciiDoc. It is already accounted for: readers use tech_documentation/README.md + chapter files; book.adoc exists only for the PDF build.

Acceptance criteria

• All chapters exist as .adoc files in docs/tech_documentation/ per the structure above and render correctly on GitHub (desktop and mobile).
• docs/tech_documentation/README.md lists and links every chapter; the root README.md links to it near the top.
• All 9 original images plus the 2 recreated screen mock-ups are in docs/tech_documentation/media/ and display in their chapters.
• make docs builds build/Technical_Documentation.pdf without errors, and the PDF contains all chapters in reading order with a generated table of contents.
• Repo search finds documentation content.
• Chapter-by-chapter parity review done; no content lost compared to the .docx.
• Stub chapters carry a visible note and have their own follow-up issues.
• The .docx is removed from the working tree (still available in git history).

Effort estimate

Roughly one focused day: the mechanical conversion is fast, and most of the time goes into restoring the heading structure (gotcha 1), placing images, and the parity review. The work splits well: media extraction and image naming, index writing, and the Makefile target are each small self-contained pieces.