Skip to main content

How do documents become a website?

Source files hold the content, navigation organizes pages, and the theme defines their appearance. A generator produces the website files.

The generation process · choose a step or play once

Content, structure, and theme are maintained separately. The static generator assembles them into plain HTML at build time, and readers open those pages directly. After editing, rebuild and publish. Incremental build support depends on the tool and configuration.

Readers open pages that are already assembled.

These notes collect practical documentation problems, approaches and tradeoffs for technical writers and developers who write product guides, API documentation or procedures. Start with the problem you have; there is no required course order.

Document markup​

Merged table cells, a notice shared by two guides, or different manuals assembled from the same content can all affect your choice of format.

Exercises use MySQL scenarios to compare document structure. They are not complete database installation or production-change procedures.

Information design​

What is missing from “Timeout, default 30”? When are tabs helpful, and when should readers see both options together?

Start with making documentation clear and useful. For a specific document, see:

  • Concepts: what something is, why it works and where the explanation applies.
  • Procedures: prerequisites, actions and a way to confirm success.
  • Reference: units, ranges, special values and when changes take effect.

Publishing​

Choose a static site generator: compare Docusaurus, VitePress, MkDocs and Antora, using this site's bilingual content, blog and interactive components to explain maintenance costs. The page includes a build/publish simulation and a minimal site template.

When does this workflow help?​

Docs-as-Code applies version control, CI checks, and peer reviews to documentation. Content is written in plain text and compiled through a generator—either alongside product code or in a dedicated repository.

This workflow helps when documentation follows product versions, needs automated link checks, or involves several reviewers. The team also needs to maintain build dependencies and deployment configuration, and handle branch merges.

Word and online collaboration tools also offer version history, tracked changes, and templates. Whether contributors are comfortable with Git—and whether existing workflows already solve the team's problems—often matters more than the format itself. If current tools meet the team's needs, keeping them is also a reasonable choice. AI can draft and proofread, but technical claims still need verification against product behavior, source code, or test results.

Future notes​

This first edition focuses on the three topics above. API consistency, AI collaboration, reader feedback, traffic paths and stale-content maintenance will follow when there are concrete cases to discuss. The review checklist and automated-check example are available now.

Corrections and discussion​

Open an issue or PR, or leave a message on the About page. Include the page URL, specific text, environment and expected result to help reproduce the problem.