Writing and delivering adapter documentation¶

This chapter explains how to prepare the documentation delivered with an adapter: generated device pages, installation instructions, and installer notes.

The published documentation has one primary audience: the integrator, who installs and configures the device. Write it in plain language and do not force the installer to understand the protocol.

Keep protocol and API documentation in the repository or documentation system where you normally maintain it. Use those documents as the source for the adapter, but do not copy them into the adapter repository, adapter image, documentation bundle, or adapter source code.

The published bundle travels inside the adapter image. You deliver one versioned image, not source code and a separate documentation archive. Protequ extracts the bundle from the image and renders the adapter pages from it.

The complete workflow¶

Use this order for a new adapter or a substantial device update:

identify the device documentation for the exact model and firmware;
write the installation guide for the integrated device;
prepare the installer-facing documentation bundle, if the delivery scope includes it;
check and preview the bundle with pq-tools;
publish the adapter image and verify the result.

Keep protocol documentation in your existing documentation system; do not copy it into the adapter project for this workflow.

1. Identify the device documentation¶

Start with the exact device model, hardware revision, and firmware family. Collect the documents that describe that version in your existing documentation system:

product or hardware datasheet;
user and installation guides;
protocol or API guide;
SDK reference and examples;
firmware release notes and compatibility notes;
converter or gateway documentation;
capacity, credential, card-format, and event-history documentation;
language-specific manuals and configuration examples;
known limitations, compatibility notes, and support contacts.

2. Write the connection guide¶

The PQ SDK Tooling generates the adapter's structured pages from the YAML declaration. It generates the device tree, object relationships, configuration fields, functions, commands, events, and capability pages. You do not need to write a second table for those relationships.

The device-specific page you write is docs/connection.md. Start from the connection guide template supplied with the adapter documentation and explain how an installer gets the device talking to PQ:

list the required hardware, cables, converters, and accounts;
state what to configure on the device or its configuration software;
give exact addresses, ports, baud rates, and security settings;
show which of those values the installer enters in PQ;
describe how to confirm a successful connection;
list the common connection failures and their fixes.

If the device needs no local configuration, say so directly. “Give the device a reachable address and enter it in PQ” is a complete connection guide when that is all the installer needs.

3. Prepare the published bundle¶

If the delivery includes a documentation bundle, create this minimum folder in the adapter project. The adapter project and PQ SDK Tooling provide the structure, templates, and checks. You can prepare and check this bundle yourself. Add an optional file only when you have its input and the delivery explicitly includes it.

<YourAdapter>/
├── adapter-registration.yaml       required
├── capabilities-coverage.yaml      required
└── docs/
    └── connection.md               required

Optional files:

<YourAdapter>/
├── access-model.yaml               only when the device stores access data
├── certification.yaml              only when a certification runner supplied it
└── docs/
    └── notes.md                    only when installers need extra field notes

The same adapter-registration.yaml drives the adapter and its generated reference pages. Keep it aligned with the implementation. Confirm that device names, models, settings, and limits are correct. Do not invent PQ functions or commands.

File	What it publishes	How to create it
`adapter-registration.yaml`	adapter identity, device tree, configuration, functions, commands, and declared events	prepare it from the implementation; use the schema; check device names, models, and limits
`capabilities-coverage.yaml`	capability-by-capability support and customer limitations	create it with `--scaffold`, complete it with `--assess`, and use the coverage reference
`access-model.yaml`	stored users, credentials, access levels, schedules, and capacities	add when the device stores access data; use the schema and the adapter implementation
`certification.yaml`	acceptance-test results and observed limitations	include it only when a certification runner supplied it; never create or edit it by hand
`docs/connection.md`	physical and network installation steps	write it for the installer using the connection guide
`docs/notes.md`	short field notes and important quirks	add only when the installer needs information not covered elsewhere

The registration file¶

Descriptions in adapter-registration.yaml are published. Check them as an installer would read them:

describe what the device or setting is;
say what value the installer enters;
state whether the value is required;
mark passwords, keys, and tokens as sensitive;
use a safe default only when the device and site rules support it.

Keep protocol details in your existing repository or documentation system, outside the published bundle. Do not put implementation assumptions or protocol internals into published descriptions.

Capability coverage¶

capabilities-coverage.yaml records whether each catalog capability works and what the installer does not get. Use --assess to set the support state and reason. Confirm whether the device supports the described capability and whether the limitation is accurate. Do not add protocol documentation to this file.

For every state other than implemented, write one plain-language limitation. Good examples:

“The clock is synchronized when the device starts, not continuously.”
“Cards can be added and removed, but they cannot be temporarily suspended.”

Avoid framework names, protocol codes, and state tokens in limitation. See the complete capability coverage reference.

Field notes¶

Use docs/notes.md for short facts that matter during installation but do not fit the structured pages:

# Notes for installers

## Important behavior

The panel permits only one active maintenance session. Close the device service tool before discovery.

## Known limitation

The panel reports historical access events only since its last restart.

Do not use this page to hide an incomplete capability assessment. Put support states in capabilities-coverage.yaml.

Certification results¶

certification.yaml is not an authoring file. A separate certification runner must write it from executed acceptance tests on the real device. pq-tools only reads the resulting file and renders the certification page. If that runner is not available or no certification run exists, omit the file and the certification page. Do not create the file manually.

4. Check the bundle¶

Run the checks yourself with PQ SDK Tooling. The tool supports the YAML and Docker steps. If another person publishes the image, hand over the already checked bundle and the image tag.

Follow PQ SDK Tooling for installation, the available operations, and the exact commands. In short, use --scaffold, --assess, --validate, and --preview in that order when the delivery includes bundle preparation. The release checklist must also confirm that docs/connection.md exists and that its steps are complete.

5. Understand the generated pages¶

The renderer builds the adapter reference from the bundle. It creates only chapters that have content:

Bundle input	Generated page
registration metadata	adapter index
`docs/connection.md`	`01-connection.md`
device types and properties	`02-configuration.md`
`capabilities-coverage.yaml`	`03-capabilities.md`
declared events	`04-events.md`
`access-model.yaml`	`05-access-model.md`
`certification.yaml`	`06-certification.md`
`docs/notes.md`	`07-notes.md`

Read the preview as an installer. Check that the first page answers “what is this?”, the connection page answers “what do I set?”, and the capability page answers “what will work?” without requiring source-code knowledge.

6. Put the bundle into the image¶

Copy the bundle into the final image stage and point the org.protequ.docs label at it:

COPY ./Pq.Adapter.Acme /pq/adapter-docs/Pq.Adapter.Acme
LABEL org.protequ.docs="/pq/adapter-docs/Pq.Adapter.Acme"

The final path segment must match the bundle folder name. The bundle is versioned with the image, so the published pages always describe the image that carries them.

The same final image must also carry the adapter identity labels. See the label reference. In particular, org.protequ.adapter="true" makes the image visible to the installer catalog.

7. Verify before publishing¶

Build the image, then inspect both the documentation files and labels:

docker build -t pqacme:dev -f Dockerfile .
docker inspect pqacme:dev --format '{{json .Config.Labels}}'

Check these points:

the image contains every bundle file;
the org.protequ.docs path exists in the image;
adapter-registration.yaml matches the running adapter;
coverage validation passes;
the preview contains the connection, configuration, capability, event, access, certification, and notes pages that apply;
descriptions contain no secrets or internal-only implementation details;
the image has a valid semver tag and the same version as its documentation;
a prerelease does not move latest.

8. Publish and verify discovery¶

Publish the image according to Publishing an adapter. The installer and public catalog read the image from the pq namespace and inspect its OCI labels. A documentation change requires a rebuild and push; retagging an old digest does not change its labels or embedded files.

After publishing, verify the tag, pull the image, and inspect the final labels. Then open the installer catalog and confirm that the adapter title, description, category, capabilities, and documentation all match the preview.

Final documentation checklist¶

[ ] The device documentation set was checked, including product and installation material.
[ ] The exact device model, hardware revision, and firmware family are identified.
[ ] The product, installation, and compatibility documents for the supported device are identified.
[ ] The generated device pages show the objects, addresses, limits, optional features, and prerequisites.
[ ] The connection section gives complete physical and network installation steps.
[ ] PQ SDK Tooling is installed through the PQ Installer and the bundle checks pass.
[ ] Protocol and API material remains in your existing documentation system and is referenced only when agreed.
[ ] Unknown or unsupported behavior is marked clearly and never replaced with a guess.
[ ] docs/connection.md gives complete installation steps, when the bundle is in scope.
[ ] docs/notes.md contains only useful installer-facing field notes, when needed.
[ ] adapter-registration.yaml and capabilities-coverage.yaml were checked with PQ SDK Tooling, when supplied.
[ ] The final text was read from an installer’s perspective.
[ ] Any agreed external document references include their title, version, and access instructions.
[ ] The image contains the bundle and the org.protequ.docs label points to it, when publishing is in scope.
[ ] The published image is discoverable in the installer catalog, when publishing is in scope.