Styling your tutorial

Now that you know what tools to use, learn when to use them.

The reader is everything

The purpose of documentation is to be read by users. Ultimately, the goal is for the documentation to be useful to the reader.

To achieve this, no matter your level of expertise on the topic, you should read the tutorial you're working on as if you were the target reader. While doing so, you should ask yourself the following questions:

  • Can the user finish the tutorial with just the provided steps?
  • Is the explanation accurate?
  • What does the user need to know to understand this tutorial?
  • Does this tutorial make the technology attractive to the user?
  • Is there any term that needs clarification?
  • Is the text well formatted?
  • Can the reader find what they need without a search field?
  • Are things being said more than once?
  • Can the users learn more by themselves?

These are not rules, just a compilation of matters found in technical documentation books. These should be addressed to the best of your abilities, where they apply.

Simply by keeping these questions in mind while writing your tutorial, your content will naturally lean towards high quality documentation.

Use tree to show the project structure

The tree command is great to show the project structure to the reader.

To select how many levels in a directory tree you want to expose, you can use the -L flag. To achieve three levels, for example:

tree -L 3

Use sentence case for titles

Prefer sentence case where possible:

Contribute to the documentation

Use Title Case only for project names, compound nouns that are known to be in Title Case, or words that come from acronyms:

Plasma Mobile

Hello World!

Personal Information Management

Use monospaced text for files, directories, code references, and short code snippets

Use backticks before and after things like:

  • ~/.config/examplerc
  • ~/kde/usr/
  • setContext()
  • cmake -B build -DCMAKE_INSTALL_PREFIX=$HOME/kde/usr.

If your code snippet has more than one line, use a code block instead.

Use () to signal functions

This applies to both links and monospaced text: setContext() or KXmlGuiWIndow::setupGUI().

Don't use parameters inside the (). The only exception is when you need to differentiate between function overloads. For example:

  • QString()
  • QString(const char *str)
  • QString(const QByteArray &ba)

Use / to signal directories

It is not always clear whenever a file name is pointing to a directory or a plain file, especially on Linux, where file extensions are not mandatory.

To avoid ambiguity, refer to directories by ending them with a slash:

  • Do: content/docs/tutorial/
  • Don't: content/docs/tutorial

Use descriptive anchors

You generally don't really need to define anchors yourself since Hugo does this for you, but sometimes section names can be too long, making links to them equally long.

Anchors can be useful to multiple people: the reader, the current writer, the future writer, and the future tester.

Make your anchors descriptive so linking to sections can be checked more easily. For instance:

You can read more about anchors in {{< ref "markdown#step5" >}}.

This will be useful to the reader and to you, but it will be less legible for the future writer and less checkable by the future tester. Prefer something similar to the following instead:

You can read more about anchors in {{< ref "markdown#howtoanchors" >}}.

Don't use monospaced text in links

Monospaced links like monospacedLink, when paired with plain hyperlinks or plain monospaced text, can look too busy when the Hugo Markdown is rendered on the website. It's best to simply use plain links for links and plain monospaced text for monospaced text.

Do: hyperlink

Do: monospaced text

Don't: monospacedLink

This binds with the question of "Can the reader find what they need without a search field?".

The tutorial should be entirely navigable by hyperlinks and it should provide easy links to the related resources used.

If you need to link to a class/type and to a property/function/variable belonging to that class/type, link both.

  • Do: "You should learn Kirigami. It provides convenient properties, such as Kirigami.Units, human readable units for sizing elements in your QML application."

The clearest exception is anchors: you should prefer link to anchors that are distant from the text that references them, such as two or three sections apart in the same text, or sections in a different page or tutorial. Follow this at your discretion.

If you are linking to QML API for the first time, mention its namespace.

If you are talking about a QtQuick Controls Button, call it "QtQuick.Controls.Button" the first time.

If it's well understood that the text is talking about QtQuick, you can just say "Controls.Button" instead.

After that you can start using "Controls Button" or simply "Button" without links, but only if there is no ambiguity. For example, if you have a QtQuick.Controls.Button and a Kirigami.Button, saying "Button" will be ambiguous and the user won't know whether you are talking about Controls or Kirigami.

Avoid cross-referencing more than once...

You should avoid providing more than one hyperlink to the same content in the same paragraph. If there is more than one, 90% of the time the paragraph can either be rephrased or split.

This can be extended to multiple paragraphs if the name of the linked thing allows it:

A [Kirigami.Action](docs:kirigami2;Action) encapsulates a user interface action.
We can use these to provide our applications with easy-to-reach actions that are essential to their functionality.
[Kirigami.Actions](docs:kirigami2;Action) inherit from [QtQuick Controls Action](docs:qtquickcontrols;QtQuick.Controls.Action) and
can be assigned shortcuts.
One feature offered by [Kirigami.Actions](docs:kirigami2;Action) on top of [QtQuick Actions](docs:qtquickcontrols;QtQuick.Controls.Action) is the possibility to nest actions.

Turns into:

A [Kirigami.Action](docs:kirigami2;Action) encapsulates a user interface action.
We can use these to provide our applications with easy-to-reach actions that are
essential to their functionality.
Kirigami Actions inherit from [QtQuick Controls Action](docs:qtquickcontrols;QtQuick.Controls.Action) and
can be assigned shortcuts.
One feature offered by Kirigami Actions on top of QtQuick Actions is the possibility to nest actions.

...but do cross-reference again where convenient

If the text transitions to a new section, the latest reference to that link was long ago, or linking to the API would suddenly be convenient for the reader, do link again.

A [Kirigami.Action](docs:kirigami2;Action) encapsulates a user interface action.
We can use these to provide our applications with easy-to-reach actions that are
essential to their functionality.

...
...
...

## Kirigami Pages

...

You can attach a [Kirigami.Action](docs:kirigami2;Action) to the `actions:` of a [Kirigami.Page](docs:kirigami2;Page).

...

Provide a full example

If the reader has no reference of what the code is supposed to look like, they likely won't know if they are following the tutorial correctly.

If your tutorial consists of creating a small project, provide the full example where needed so the user has a reference to compare the work they've done following through the tutorial.

Use the readfile and snippet shortcodes as well as code blocks to achieve this.

Do not abuse alerts

The {{< alert >}} shortcode is great for talking about optional content without interrupting the reading of the main tutorial. But that's precisely it: if the number of alerts is high enough to interrupt the reading of the main tutorial, then there are too many.

Moreover, if you can see no practical difference between the text being inside and outside of an alert, then chances are it is required as part of the tutorial and you should not use an alert at all.

Use collapsible boxes for long lists or content

Collapsible boxes like the following:

<details>
  <summary>Click here to open this collapsible box</summary>
  Contents of the collapsible box
</details>

Can be used for optional content that really should not be taking space from the page and from the main content, which might be the case for really long lists or alerts. Use this rarely.

Follow standard documentation practices where it makes sense

Here are a few free resources to learn about technical documentation:

Here are a few highlights from the Google Technical Writing Guide that effectively summarize content seen in most technical writing books:

Write The Docs is a global community of technical writers, and they provide lots of content that you can use to improve your technical writing skills:

Here is a list of recommended Write The Docs talks that you should see: