The last decade of developer documentation craft was built for SaaS. Web APIs, pure functions, versioned endpoints, stateless requests. Hardware SDK documentation breaks almost every assumption that craft rests on. A docs team trained on SaaS patterns will produce firmware docs that are worse than the team started with, because their instincts point the wrong way: simplify the prerequisites, collapse the version matrix, hide the errata behind a link, trust the tutorial because the snippet compiled.

This post is for the people writing docs for products with a serial port.

Hardware SDK documentation operates under four constraints that web SDK documentation does not: toolchain complexity, silicon variance, long-lived devices in the field, and the absence of live reproducibility. Each constraint breaks a content pattern the SaaS docs world takes for granted. Teams moving from SaaS docs to hardware docs need a different playbook, not a version of the old playbook with more caveats. Below we name the four constraints, show what a working hardware docs stack looks like against them, and explain what an AI assistant layer can and cannot do on top.

The four constraints#

1. Toolchain complexity#

A hardware SDK typically requires, at minimum: a specific compiler version (ARM Compiler 6.x in Keil MDK, a pinned GCC arm-none-eabi release, or an IAR EWARM build), a specific IDE or command-line build system, a specific set of device pack or DFP files, a specific debug probe driver (J-Link, CMSIS-DAP, ST-Link) and its firmware revision, a specific bootloader or secure boot configuration on the target, a specific host OS with specific udev or USB filter rules, and a specific hardware revision of the board itself. Any one of those wrong and nothing works. Worse, many failure modes are silent: the image builds, flashes, and boots, then misbehaves two hours in because the linker script came from the old DFP.

SaaS docs solve the first two dimensions (language version, library version) and ignore the rest. A Python SDK page that says "requires Python 3.11+" has covered almost the entire support surface. A firmware SDK page that says "requires GCC 12" has covered perhaps a fifth of it.

The implication is structural. Prerequisites are not a paragraph; they are a matrix. Every page that assumes a toolchain has to resolve to a specific row in that matrix: compiler and version, debug probe and firmware, device pack version, host OS, board revision. The matrix lives at a canonical URL and is the thing release notes update. Tutorial pages link into a specific row rather than restating prerequisites inline, because restating them guarantees drift. When a customer opens a support ticket, the first question your docs should let them answer, without help, is "which row am I on?"

2. Silicon variance#

A single SKU ships with three different silicon steppings over five years. Mask revision A0 has a DMA bug on channel 3 that the hardware team worked around in B1; B1 fixed DMA but introduced a different I2C clock-stretching timing; C0 fixed both and added a new low-power mode that the older HAL does not expose. The SDK supports all three parts. The reference documentation, almost always, documents one, usually the newest. Everything else is in the errata PDF that nobody reads until a shipping product fails qualification.

This is not a minor quality-of-life issue. A developer reading your DMA_Start() page is trying to write code that will run on whatever silicon is in the device on their desk, which may not be the silicon your writer had in front of them. If the page does not tell the developer which steppings the documented behavior applies to, the page is a trap.

The implication: reference pages need a machine-readable "applies to" field that names silicon revisions, not just SDK versions. Behavioral differences between steppings belong in the reference page for the affected peripheral or function, in a callout at the point of divergence, with a link out to the full errata entry for readers who need the deep explanation. The separate errata PDF still exists, because the silicon team maintains it and regulators expect it, but it is no longer the primary surface. The primary surface is the reference page the developer already has open.

3. Long-lived devices in the field#

A SaaS product's "old users" are people who signed up last year. A hardware product's "old users" are an industrial customer who deployed 50,000 gateways in 2018, cannot field-update half of them without a truck roll, and will be writing new application code against firmware v1.2 for another four years. Meanwhile your newest customer is starting a greenfield design on firmware v4.0 this quarter. Both are reading your docs this week.

The SaaS instinct is to deprecate. Mark the old behavior, add a migration guide, sunset the page. That instinct is wrong here. You cannot deprecate a documented behavior and expect readers to migrate, because the device in the field is not going to migrate. The v1.2 developer is not a laggard; they are a customer whose bill of materials and certification scope were frozen years ago.

The implication: versioned documentation is not a nice-to-have, it is the product. Every reference page exists in every supported firmware branch, addressable by URL. The site defaults to current, but older branches are first-class and not hidden behind a redirect to "the latest." Search and retrieval scope to the reader's selected version. Release notes link both forward (what changed in the next version) and backward (what behavior was removed or altered from the previous one). When a HAL function's signature changes between v2 and v3, both signatures stay documented on their respective branches, forever, because there are boards in a substation somewhere that will outlive the engineer who wrote the code.

A note on promotion. "Current" on a hardware doc site should usually mean "the current long-term-support branch," not "the bleeding tip." The LTS branch is what most readers are on. The tip branch is available, labeled, and not the default.

4. The absence of live reproducibility#

A SaaS tutorial can be verified by a CI job that runs the code samples every night against a staging environment. A hardware tutorial needs a physical device, a specific debug probe over JTAG or SWD, a specific host with the right USB stack, power sequencing on the board, sometimes an oscilloscope to confirm the signal the tutorial claims to produce. You cannot CI-test most of the samples. You can, with effort, manually test them on a rig, and only for the exact combination of stepping, toolchain, and probe firmware that rig has.

That gap is the single biggest source of silent rot in hardware docs. A sample that compiled cleanly in 2023 against DFP 2.4.1 on an A0 part may fault on a C0 part with DFP 2.7.0, and no automated process will tell you. The tutorial page looks fine. The reader files a bug that gets triaged as "works on my machine."

The implication is procedural, not technological. Every sample on every tutorial page carries a visible test stamp: hardware revision, SDK version, toolchain version, debug probe and firmware, host OS, date, and the name or ID of the person who ran it. A sample whose stamp is older than the current SDK release is visibly flagged, not silently broken. Releases gate on re-running a defined tier of tutorials on a defined rig, and the docs team owns the rig calendar. The writer does not have to be the one on the probe, but someone does, and the page has to say who and when.

This is unglamorous work. It is also the difference between a docs set that engineers trust and one they route around.

What a working hardware docs stack looks like#

Against those four constraints, the stack has six load-bearing components. Each one maps to one or more constraints, and all of them are mutually reinforcing: the matrix feeds the test stamps, the test stamps feed the retrieval filters, the retrieval filters feed the assistant.

A toolchain compatibility matrix at a canonical URL. One page, one table, updated at every SDK release. Rows are supported combinations of compiler, IDE, device pack, probe firmware, host OS, and board revision. Every tutorial and reference page links into the specific row it assumes. Customers quote the row number in support tickets.

Revision-tagged reference pages. Every reference entry carries a machine-readable field that names the SDK versions and silicon steppings the documented behavior applies to. The field is frontmatter, not prose. Search, sidebar filtering, and retrieval all respect it. When a reader lands on the page, the page tells them up front which world it is describing.

Multi-version navigation as a first-class feature. The site serves every supported firmware branch at a stable URL pattern. The version selector is persistent. Default is the current LTS. SEO canonicals point to the version-less landing page for each topic, not to the current version, so link equity does not churn on every release. Older branches are not archived to a subdomain that search engines treat as dead.

Dated test stamps on every sample. Hardware revision, SDK, toolchain, probe, host, date, tester. Visible on the page, machine-readable in frontmatter. A scheduled job flags stamps older than a defined age. Release notes carry the retest summary.

Errata inline, not segregated. Stepping-specific behavior lives in a callout on the reference page for the affected function, collapsible for readers on newer parts. The source of truth for the callout is the same errata database the silicon team maintains, pulled in at build time. The full errata document still exists; it is no longer the only place a working developer would find the information.

A firmware-version-aware assistant, if there is an assistant at all. More on this below, because it is where most teams get it wrong.

What the AI layer changes and what it doesn't#

Retrieval against a hardware doc set is harder than retrieval against a SaaS doc set, and not by a small margin. The correct answer depends on dimensions a SaaS doc set does not even model: which silicon stepping, which SDK branch, which HAL version, which compiler, which probe firmware. A retrieval system that indexes the docs as flat text and ranks by semantic similarity will cheerfully return the C0 answer to an A0 question, because the C0 page is newer, longer, and linked from more places. The user will believe it. The device will fault.

An AI assistant without access to those dimensions will confidently give the wrong answer for the wrong hardware. Not because the docs are bad. Because the question is under-specified, and the assistant has no scaffolding to notice.

The fix is not a better model. The fix is three things the docs team owns:

Frontmatter discipline, so every chunk the retriever sees carries its SDK version, silicon stepping, and HAL layer as structured metadata, not as prose buried three paragraphs in.
Retrieval filters that scope to the user's declared context before ranking, the way a good search UI scopes by version selector before running the query.
An assistant UX that asks for firmware version and board revision before answering ambiguous questions, and that shows the scope of the answer ("this applies to SDK 3.x on B1 and later") in the response itself.

The assistant is not a substitute for the four constraints. It is downstream of whether the docs encode them. A hardware doc set that has done the structural work gets an assistant that is trustworthy on the first query. A hardware doc set that has not, gets an assistant that hallucinates with confidence and erodes the trust the written docs had earned.

If you're moving a SaaS docs team onto firmware#

Give them the time to unlearn. The patterns that made them good at Stripe-shaped docs will make them slow here, and their instincts to simplify, to deprecate, to trust the snippet because it rendered, will remove the metadata the hardware reader needs most. The craft is compatible. The constraints are different, and the constraints are the spine. Encode them into the information architecture, the frontmatter, the release process, and the retrieval layer, and the docs start to feel like something a firmware engineer wrote for another firmware engineer. Skip them, and you get SaaS docs with the word "hardware" pasted on, which is what your readers are already tired of.