Skip to content

Prose style guide

"But far more numerous was the herd of such,
Who think too little, and who talk too much."
~ John Dryden

This is a deliberately short guide to writing, editing and English usage to be followed by the authors of Future Ancestors' documentation. It complements the advice given in the technical style guide for in-code comments and technical content. This document covers everything else: the editorial and narrative writing intended for people to read. It will also help guide those translating our documentation, so the project's voice survives, reflected in the idioms of the target language.

It assumes familiarity with our ethos, our position on care of community and for whom we create.

Why?

Writing is a craft: another example of technique in service of expression.

Therefore we need to explore, illustrate and articulate the expectations, idioms and examples of this craft. Form, structure and process are necessary, but not enough. Tone of voice, demeanour and personality are also needed to make a space in which the reader engages, learns and imagines.

We reach for this ineffable quality of connection through our authorial techniques, but those techniques only become expressive when they reflect our humanity, personality and way of attending. Alas, a well-structured and technically correct page of prose is not enough if it lacks this ineffable quality and fails to engage and enrich the reader.

It's the documentary version of the difference between a technically correct (yet boring) musical performance that merely presents notes, and one that excites, inspires and engages because the performer risks revealing a part of themselves that connects with others.

We know the ineffable quality is there when the reader is so connected with our prose they feel lost in their own potential and creativity. The ineffable quality is one you fail to notice. But were we to remove this quality, the reader would feel something was missing.

Thus, reading becomes enrichment.

Our voice

Our documentation is a collaboration of diverse authors, but each page speaks with the voice of its project. Those voices are not identical: Invent sounds more approachable and beginner friendly than BFP or ImportPython, which speak to technically astute readers. Yet every project shares a recognisable Future Ancestors accent - a family resemblance and sense of place that reflects how we engage the reader. What follows is that accent.

We write as a knowledgeable colleague, not an authority figure. We assume the reader is capable and treat them accordingly, with respect. Clear and direct, never condescending. Occasionally witty, never trying to be funny. Confident without being boastful.

We never say "simply do X". If someone is struggling, it isn't simple.

We never say "users". They are "practitioners". For whom explains the difference, and is the justification for why it matters.

Registers

One voice, with three registers.

  1. The poetic belongs at thresholds: welcomes, openings, codas - the places where the reader's state is the subject, where writing should inspire the imagination.
  2. The colleague carries the body of the work: explaining, illustrating, empowering. The reader receives, reflects and integrates such prose into their creative process.
  3. The conventional serves the reference, where predictability and conventions are expected and a strength. It unambiguously provides the essential nugget of knowledge clearly, efficiently and without ceremony.

Switch registers only at structural boundaries and never mid-flow - a heading, a rule, a section break - so such modulation feels composed. The craft is knowing when to change register so the modulation is heard as deliberate rather than accidental. Such a change should enrich and enlarge the reader's attention.

We harness and switch between registers to create a mood. We are literally guiding the quality of the reader's attention. Take great care!

Artistic licence

Not everywhere!

Each aspect of the documentation has a different purpose:

  • Narrative pages - getting started, the manual, the worked examples. This is the place for living prose: pacing, story, the well-chosen metaphor, the moment of delight. A reader here is learning, and learning is helped by engaging prose and guiding the quality of the reader's attention through use of register.
  • Explanations - the design decisions, the why-it-is-this-way material. This is where the writing thinks aloud. Honesty and clarity matter most: tell the story, name the trade-offs, admit the warts, credit the influences.
  • Reference - the API surface, the attribute tables, the error hierarchies. Here, predictability and convention are required. Follow the established customs of good reference material and resist the urge to decorate. Someone mid-task wants an answer, not a performance.

Mechanics

  • British English spelling.
  • Never an em dash; use -.
  • No serial comma, unless its absence would mislead.
  • Attribute quotations with a tilde: ~ [Author](link).
  • Lines of Markdown source no longer than 79 characters wherever possible.
  • Examples are real: they run, they are tested, and where the page supports it, they run live in the page itself thanks to ImportPython.
  • Link to upstream documentation rather than restating it: MDN for web platform matters, a runtime's own docs for runtime matters. A project's documentation names its own concrete sources; this guide stays general.
  • Do not strip out voice or register to make a translator's life easier. A good translator will idiomatically translate these too.
  • Remember the second audience: these pages are read by machines assisting humans. Accuracy and self-containment serve both audiences; nothing about writing for machines excuses dull writing for people.

The test

Read the page aloud. If you sound like a form being filled in, start again. If you sound like yourself explaining something you care about to someone you respect, it is probably done.

Therein lies the ineffable quality.