Skip to content
Contact Support

Writing Principles

See also

These principles decide what to write, whether to write it, and how much. Create a New Page and Formatting cover how it should look. They apply to everyone who writes here, people and AI agents alike.

Our readers are researchers with a wide range of HPC experience, usually in the middle of trying to get something done.

Principles

  1. Start from a reader need. If you cannot say who needs the page and what they will do with it, do not write it.
  2. One page, one job. Every page is a tutorial, a how-to guide, reference or explanation (Diátaxis). Do not mix them: a how-to guide that stops to explain background should link to an explanation instead.
  3. Every page is page one. Most readers arrive from search, not from the previous page. A page must fully serve its main task on its own. State prerequisites, and use links only for tangents.
  4. Common case first. Lead with what most readers need. Put edge cases and rare failures in admonitions (collapsed if long) or on linked pages.
  5. Simple and mostly right, but exact where it counts. Simplify explanations freely. Commands, paths, limits and policy must be exact and work when copied.
  6. Say it once. Each fact has one home. Elsewhere, give a one-line summary and link to it. A little repetition is fine if it saves the reader a click, but never copy the details. Tutorials are the exception, see Tutorials and Mainline Docs.
  7. Plain words, and fewer of them. Put the most important information first. Use active voice, short sentences, descriptive headings and NZ English. Cut anything that does not help the reader act or understand.
  8. Write less that lasts. Every page has to be maintained. Link to vendor documentation instead of copying it. Leave out details that go out of date (versions, dates, screenshots of web pages) unless they are generated, for example with macros.
  9. Be findable. Write titles and descriptions in the words readers search with, usually the task or the question. The description also feeds search, llms.txt and the docs search assistant.

Should This Be Written?

  • No clear reader need: do not write it.
  • An existing page covers it: improve that page.
  • Vendor documentation covers it and nothing about it is specific to Mahuika: link to the vendor documentation.
  • A one-off answer for one person: answer the ticket. Write it up only if it is likely to come up again.
  • Only true for a short time (an outage, a change): write a dated announcement in docs/Announcements/, not a permanent page.

New Page or Existing Page?

  • The same purpose as an existing page: add to that page.
  • A different type of page (see principle 2), or a separate task readers would search for: make a new page.
  • Too long is not a reason on its own. First move detail down the page or into admonitions. Split only when parts serve different tasks or readers.
  • A new page needs a place in the nav (.pages.yml), links from related pages, and tags.

Tutorials and Mainline Docs

Tutorials (pages with status: tutorial) and the mainline docs (every other page: how-to guides, reference and explanation) cover much of the same ground on purpose. A tutorial is for someone learning a topic, a mainline page is for someone getting a task done.

  • Tutorials stand alone. A tutorial restates the basics it needs, with more examples worked through step by step, so it can be followed without leaving the page. Repeat the basics in full, not as a one-line summary.
  • Mainline pages stand alone too. A mainline page covers its own basics and never relies on a tutorial to explain them.
  • Covered in one is not a reason to leave it out of the other. When adding content, decide what belongs in each.
  • Exact facts match. Commands, paths, limits, policy and example output must agree between the two, and use the same macros. When you change one, check the other.

Link in both directions:

  • From mainline pages to tutorials: link to a whole lesson as a prerequisite for readers new to the topic, or to a specific exercise as a more detailed worked example.
  • From tutorials to mainline pages: link in the postrequisite admonition as what to read next, or at a point where a reader may want more detail than the lesson gives.

The tutorial page structure follows the Carpentries lesson model.

Further Reading