FerryDocs
ContributingDocs site

Write a page

Each page is short and starts with a picture. The file docs/AUTHORING.md is the contract.

Edit on GitHub

Read the contract. docs/AUTHORING.md has the rules for each page.

1 / 5

The contract

Read docs/AUTHORING.md first. It is the contract for each page, and the only place for the rules of the text. This page gives the short version.

The model is content/docs/concepts/deploys/.

The short version

  • One idea per page.
  • A figure before the text.
  • 220 words of sentences at most.
  • Short sentences, active voice, one name for one thing.

The sentence rules come from ASD-STE100, .

Measure the page

In docs/
npm run check-content -- -v <path>

At least 80% of the sentences of a page must pass.

Write what the code does

  • Use examples that run, with the real defaults: http://127.0.0.1:7878 for the API and http://<name>.localhost:8080 for apps.
  • Document only what the code does. Check commands and flags against --help. Check behavior against the source.

The npm scripts

Eight npm scripts in docs/ run, measure, generate, check and build the site.

Files, URLs and the sidebar

The URL of a page follows the path of its file. A meta.json file gives the order in the sidebar.

On this page

The contractThe short versionMeasure the pageWrite what the code does