Writing docs

This page is for people who change the docs of Lasbolt. The docs are in docs-site/. They change in the same commit as the code that they describe. The contract is section 18 of the design contract.

Where pages live

Each page is a Markdown file under docs-site/content/docs/. The folder is the section.

The page tree is fixed in section 18.6 of the design contract. Do not add or move a page without a change to that section.

Each page has front matter with three keys:

---
title: Install
weight: 2
description: One sentence about what the page is for.
---

The weight sets the order in the menu. Keep the weight of the skeleton.

Write the page

Use the ASD-STE100 style (Simplified Technical English). The rules that matter most:

• Write short sentences. Put one idea in each sentence.
• Use the active voice. Write “Run the command”, not “The command must be run”.
• Use imperative verbs in steps. Put one action in each step.
• Use the same word for the same thing every time. Do not use a synonym for variety.
• Start with what the page is for. Then give the task.
• Do not write marketing words. The tone is in Brand: plain and technical.

Use the parts in Page parts:

• Steps for a procedure.
• Tabs when the steps differ by platform.
• Callouts for a warning or a note that the reader must not miss.
• Mermaid when a diagram says more than text. Use a fenced block with the language mermaid.
• Cards for a list of links with a short text.

Link to other pages with root-relative paths, such as [Install](/docs/server/install/). Do not link to a page that is not in the page tree.

Check what you write

Every command, flag, path, menu name and output on a page must match the code. Run the command on a real server before you commit. The test harnesses (pwharness, make run) are enough. Do not describe a feature that is not built. If a feature is planned, say “not available yet” in one line, or leave it out.

Run these commands:

make docs-check takes a few seconds. It fails for any of these:

1. The build has a warning, or a ref or relref link is broken.
2. A page loads an asset from another origin (remotecheck).
3. An internal href or src in the built site does not point to a file, or a #anchor is not on the target page (linkcheck). The message lists each broken link with the page that has it.
4. A generated item has no help text or no purpose (see the next section).
5. A written page has no description, or it is a stub: it still has the skeleton sentence of an empty page, or it has an open to-do marker (stubcheck).

make gates runs make docs-check with the other gates.

Generated pages

The pages of the Reference section, the design contract, Build and test, Brand, Logo and the threat model are not written by hand. Do not edit them. The files are ignored by git, and make docs makes them again every time.

Each generated page starts with a callout that names its source. The generator is docs-site/tools/cmd/refdoc. It reads:

• the --help output of the three programs,
• the Go source (with go/ast), for the flags, routes, error codes, ops and exit codes,
• the tools/list answer of lasbolt mcp, for the MCP tools,
• the repository files, for the copied pages.

If a generated page is wrong, change the source. To change the help text of a command, change the Go code.

The code cannot say what a route is for or what an op does. A text file for each kind has that text. The files are in docs-site/tools/cmd/refdoc/desc/:

Each line is key | text. The generator works in both directions. A route in the code with no line fails the build. A line for a route that is gone fails the build too. When you add a route, an op or an error code, the build tells you which line to add. To see the keys and the draft text from the code comments, run REFDOC_DRAFT=1 bin/refdoc ref -root . -content docs-site/content -bin bin/docs.

A flag of lasboltd must have its environment variable in its help text, in the form (env LASBOLT_NAME; default value). The generator reads the table of the configuration page from it.

Screenshots

Screenshots come from the harnesses: make shots (web app and extension), make ios-e2e (simulator) and make android-e2e (emulator only). Never use a screenshot from a real phone. Do not edit a screenshot by hand.

To use a screenshot:

1. Run the harness. The files are in .harness/shots/.
2. Add one line to docs-site/shots/<section>.txt: the path of the source relative to .harness/shots/, a space, and the path of the copy relative to docs-site/static/shots/.
3. Run make docs-shots. It copies the files, and it fails if a source file is missing.
4. Use a normal Markdown image with alt text: ![A short description](/shots/section/name.png).

Keep to the screenshots that help the reader. About ten for each section is a good limit.

Versions

The site at / is built from master. The version menu comes from the git tags of the form vX.Y.Z. The generator writes docs-site/data/versions.json. Until the first tag, the menu has only master.

To publish a version, check out the tag and run make docs-deploy DOCS_VERSION=vX.Y.Z. This builds the site with the base URL https://docs.lasbolt.com/vX.Y/ and uploads it to the folder /vX.Y/. The other folders stay as they are. A deploy without DOCS_VERSION uploads the root and keeps the version folders.

Search

Search runs in the browser. The build makes one index of all pages, and the generated pages are in it. A command, a flag, a route or an error code is a heading or a table row, so search finds it by its name.