Writing docs

A docs page is one plain HTML file. There is no build step: you edit the file, refresh the browser, and run one command to keep search current.

Preview the docs

Open docs/index.html in a browser. Nothing has to run. To browse them at a real address (for example from a phone on the same network), serve them:

npm run docs

The docs are then at http://localhost:5180. Use npm run docs -- --port 5190 for another port.

Add a page

1. Copy the skeleton below into a new file in the right folder of docs/. A page in a folder uses ../ for its assets; the home page uses none.

2. Add the page to docs/assets/nav.js, in the place a reader should meet it. The title in the list must match the page's heading.

3. Rewrite the search index:

   npm run docs:index

4. Run the docs checks:

   npm run check:docs

While you are still writing, npm run docs:lint -- docs/contributing/writing-docs.html checks just that page (its shape, links, paths, writing rules and sections) without needing it in the navigation yet.

The page skeleton

Every page is a whole HTML document, so it opens on its own and can be lifted into another site. Only what is inside <main> is content; the header, sidebar, contents list, previous and next links come from docs/assets/docs.js and docs/assets/nav.js.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Search | Arc CMS docs</title>
  <meta name="description" content="One sentence: what this page lets you do.">
  <meta name="docs:sources" content="functions/src/search, src/app/core/search">
  <link rel="stylesheet" href="../assets/docs.css?v=b4b0869ba9">
</head>
<body data-root="../" data-page="features/search.html">
  <main>
    <h1>Search</h1>
    <p class="lead">What you can do, in one or two sentences.</p>
    ...
  </main>
  <script src="../assets/nav.js?v=d45a1d4f68"></script>
  <script src="../assets/search-index.js?v=a8c311e57e"></script>
  <script src="../assets/docs.js?v=058ca80717"></script>
</body>
</html>

docs:sources

The docs:sources meta lists the files and folders the page describes, separated by commas, or none when the page is not about any code. It does two jobs. A check fails when a listed path no longer exists, so a rename cannot leave a page pointing at nothing. And npm run docs:affected reads it to tell you which pages to review after a change (see Docs and tests are part of done).

Writing rules

• Task first. Start with what the reader can do after the page, then the shortest way to do it. Reasons come second and stay short.
• One fact, one place. If another page owns a fact, link to it instead of repeating it.
• Present tense, plain words. The docs say how Arc CMS works today. No history, no "recently", no "now".
• Numbered steps and copyable commands. Put each command in its own <pre><code> block, and run it before you publish the page.
• Recommend one way. If there are options, give the recommended path first and the alternatives on a labelled line after it.
• American spelling, the same as the interface.

Some things are refused by a check, on every page:

• Em dashes and en dashes. Use a comma, a colon, a full stop, or "such as".
• Internal terms: task or phase codes, branch names, and our own Firebase project ids.
• A mention of the specs folder. The docs never point into the working papers.
• Placeholder text such as a leftover to-do.

Paths, files and code

Write a path in <code> and the checks confirm it exists in the repository, so a moved file is caught. A file the reader is told to create is written with the new class so it is not checked:

<p>Open <code>src/custom/features.ts</code> and create <code class="new">src/custom/pages/deals.page.ts</code>.</p>

A path only older versions have, which a page tells the reader to move away from, is written with the old class, also unchecked.

Placeholders such as {lang} or YOUR_PROJECT are skipped.

Callouts

Three callouts exist. Use them sparingly.

<div class="note"><p>...</p></div>
<div class="warn"><p>...</p></div>
<div class="trap"><p>...</p></div>

Numbered steps

Give an ordered list the steps class for large numbers, as on this page:

<ol class="steps">
  <li><p>Do this.</p></li>
  <li><p>Then this.</p></li>
</ol>

Feature pages

A page in the features folder has the same sections, in the same order, so a reader always knows where to look. A section that does not apply says so in one line.

1. What it is
2. Turn it on or off
3. Set it up
4. Use it
5. Extend it
6. What it stores
7. Who can do what
8. Troubleshooting

A check fails when a feature page misses one, or has them out of order, and when a switchable feature has no page of its own.

The checks

The checks run with the whole test suite and on their own with npm run check:docs. They fail on:

The app's own pages

An app built on a copy of Arc CMS keeps its own docs in docs/custom/. Core never touches that folder, and the checks above skip it.