Starcraft style guide¶

This is the style guide for user and developer documentation in the craft apps and libraries. It’s a supplement to the Canonical Documentation Style Guide.

Tone¶

Starcraft is for developers, which means Starcraft is for humans. In our tone we must never forget we’re speaking directly to the person behind the device.

Here are fundamentals for the persona we adopt when speaking to the user. They’re the foundation for our style:

We write, primarily, as teachers and guides. We provide for the user’s understanding, and guide their work.
We are the team behind the Starcraft products. We take responsibility for them.
Let that which is exciting, inspiring, and interesting come across on the page. If technology has this effect on you, allow it to come out in your writing.
Documentation is one side of an ongoing dialogue with the user. Dialogue is conversation, so write directly and straightforwardly, in plain language. Write like the user will respond to you directly – they often do.
Be brief. The user’s time and attention is a gift they don’t hand out lightly. Be responsible with it. Don’t squander it.
In the course of events, identify the person in the loop. Humans come to decisions, have opinions, and make mistakes. Processes, systems, and machines don’t.
Many ideas in computing are abstract, metaphorical, and even at times whimsical. If it helps the user understand, use analogy and metaphor. Grounding an idea in a familiar concept is an effective technique for communicating abstract and complex ideas.
When something is difficult, acknowledge the pain it causes.
When something is uncertain, be forthcoming about why.

Inclusivity¶

Singular they and them¶

Don’t presume a gender when referring to a nominal or anonymous person:

Once he installs the app

Wait for the user to make her choice

Do use singular third-person pronouns:

Once they install the app

Wait for the user to make their choice

Names for people¶

Don’t use gendered names in examples or placeholders:

Alice

Bob

Carol

David

Do use unisex names:

Alex

Blair

Cam

Devin

Accessibility¶

Image alt text¶

All images must have alt text. The W3C Images Tutorial provides complete guidance for how to write one.

Relative positioning¶

Don’t refer to relative positions and directions:

The above example

The code below

The Render node at the bottom-right of the chart

Do refer to chronological sequence, linear sequence, or the item itself:

The previous example

The following code

The Render node

The user is able to locate elements in space in multiple senses. Relative positions in a document, a graphic, or an interface are likely to change, therefore documenting them precisely increases maintenance debt. They also aren’t helpful when the page is recited by a screen reader.

Names¶

Product names¶

Don’t modify the product names, even if it’s grammatical:

Starcraft’s

Starcrafts

Starcrafty

Do keep product names discrete and unaltered:

Starcraft

Version names¶

Don’t use special formatting for version names:

Starcraft 9

Starcraft v9.0.1

Use regular formatting instead:

Starcraft 9

Starcraft 9.0.1

Don’t refer to changes in time when referring to a range of versions:

Starcraft 8 or newer

earlier than core26

Use higher and lower instead:

Starcraft 8 or higher

lower than core26

Software and package names¶

Don’t format software and package names as code:

download and install curl

the firefox snap

core26

Do write software names in plain English, using the spelling provided by the authors:

download and install curl

the Firefox snap

core26

Some commands, programs, and library names have become generic as verbs, tools, or products. For example, sudo and grep started as packages but have since entered common parlance.

Feature and component names¶

Don’t format feature and component names as code:

the python plugin

the gnome extension

Do format feature and component names plainly:

the Python plugin

the GNOME extension

The rule of thumb is, do you always qualify the name as belonging to the class of the feature? In other words, does it fit the pattern the [name] [feature type]? If yes, it should be formatted normally.

Code unit names¶

Don’t refer to code unit names without context:

call setup()

if your package doesn’t have a name

Do qualify what the name is to disambiguate it:

call the setup() method

if your package’s name key isn’t set

Links¶

The prose of a document should be naturally-flowing, plain English. Whenever a link appears in the text, it threatens to harm that flow, because a link is an invitation to go somewhere else. Carefully consider:

How the link fits into the context of the preceding discussion. Does the text naturally lead to this link? Does it feel like it belongs? If you were having a conversation with a friend, and they pushed their phone up to your face without warning, it would be quite rude. That’s what an unexpected link feels like on the page.
What benefit the user gets from the link. A link is a call to action. But there are many actions the user could take in a document, including skipping the link. Does the link’s text, and the text surrounding it, help the user decide whether to click on it?
If you start writing “See [link] for more details”, don’t. That sentence is of no help to the user. Instead, consider how to invite, or call, the user to click on the link.

Don’t set high expectations or make promises you can’t keep with a link:

You can visit Migrations in the Django documentation to learn how to

Do straightforwardly describe what’s at the other end of the link:

Migrations in the Django documentation describes how to

It’s better to be descriptive. You can’t guarantee that a link will provide positive benefits like learning and discovery.

External link format¶

For named external links, avoid end-of-file links:

`Migrations`__

# Rest of document...

.. _Migrations: https://docs.djangoproject.com/en/6.0/topics/migrations/

Prefer the inline format, with two underscores (_):

`Migrations <https://docs.djangoproject.com/en/6.0/topics/migrations/>`__

In long documents, the source is more readable, comprehensible, and easier to maintain when external links are declared in the same location as they’re used. Internal references are formatted inline, so the authoring experience is more congruent with this pattern.

The double underscore blocks Sphinx from making the external link into a named reference.

Examples of good links¶

A link to another site:

Discuss your ideas on the Snapcraft forum.

A link to an action in another how-to guide:

First, install Brew.

A link to a different section in the documentation:

Without such a connection, the snap fails to build. Guidance on sourcing information is available in External package information.

A link to another documentation set:

The snap command itself has many diagnostic features that can help with debugging runtime and configuration errors. Debugging snaps in the SnapD documentation covers how and when to use them.

Reference labels¶

Format Sphinx labels as:

.. _<diataxis-type>-<page-title>-<id>

For example:

.. _how-to-starcraft-style-guide-sphinx-labels

Within a documentation set, every label must be unique. A systematic and semantic approach reduces the chances for collisions and makes identification by humans much easier.

Between documentation sets, they may be connected through Intersphinx. The namespaces of every connected documentation set are pooled. It’s possible to have collisions if one set refers to another through a :ref: lookup instead of :external+<set>:ref:.

Admonitions¶

Wherever possible, avoid admonitions, also known as callouts, like notes, tips, cautions, and warnings. They compete for the user’s attention and become noise when overused. Aim for at most one in a document.

Prefer the generic admonition type:

.. admonition:: If you're thinking about using an admonition
    :class: tip

    Try writing a plain paragraph first.

The message you put in the admonition becomes meaningful for its time and place, which is much more helpful to the user than a generic, context-free Tip.

Code blocks and quotations¶

The purpose of code in documentation is to make bare the literal words and expressions that have effect in the software. Format code in contexts when you expect the user to immediately make use of it.

Use as little code as possible. Readers have complete availability of our source code. They come to the documentation to read in a natural language.

Code directive¶

Use the code-block directive for code blocks, and always include the language:

.. code-block:: bash

    ls -la

If no language applies, then the text probably isn’t code, and different markup is needed.

Error messages¶

Don’t quote error messages and statuses as code:

.. code-block::

    Code: macaroon-permission-required

Use the terminal directive instead:

.. terminal::
    :output-only:

    Code: macaroon-permission-required

File paths¶

Format file paths in text like this:

/directory/from/root/

relative/directory/

path/to/file

path/to/file.ext

There are many files in Linux that don’t have extensions, such as /bin/bash and ~/.gitconfig. Including the final slash makes it less ambiguous about whether we’re describing a file or a directory.

Punctuation and symbols¶

Colons and semicolons¶

Avoid colons and semicolons inside paragraphs:

There was only one thing to do: dance.

It was cold; I ran home.

Do use full stops:

There was only one thing to do. Dance.

It was cold. I ran home.

The grammar rules for when to use semicolons, colons, and commas vary between regions and writers. It’s easier to sidestep them completely.

Colons and semicolons are difficult to see when skimming, and are a barrier for blind users and those with vision impairment.

Use colons to connect to an element on the next line:

Run the following commands to clear the cache:

Quotation marks¶

Don’t use quotation marks to cite terms, borrowed words, names, or titles:

also known as “crafting” a package

according to “Design Patterns”

Do use emphasis instead:

also known as crafting a snap

according to Design Patterns

Quotation marks around words can sound insincere or sarcastic. Many cultures and languages don’t use them, so their meaning can be lost.

Non-linguistic symbols¶

Don’t use symbols as shorthand:

✔

✕

🚀

Do use single words:

Yes

No

Launched

Symbol meaning varies across cultures and languages. Symbols aren’t always compatible in screen readers.

Preferred terms¶

Technical terms¶

Instead of…	Use…
application	app
Apt apt	APT
craft tool crafts	craft app
DEB `.deb`	Debian package
keyword field	key

Inclusive and nonviolent terms¶

Some longstanding words in computing are biased, discriminatory, or violent. Use these replacements:

Instead of…	Use…
black hat	malicious actor attacker
blacklist	blocklist
dummy	placeholder
grandfathered	exempt
hang	stall
hit	press
illegal characters	invalid characters unsupported characters
kill terminate	end halt
man-in-the-middle	machine-in-the-middle
master	primary main
sanity check	safety check confidence check
slave	secondary replica mimic sample example
white hat	researcher security specialist
whitelist	allowlist