Documentation style guide

This page provides guidelines on how to write documentation for the Stackable platform. The guidelines cover overall document structure, text appearance and formatting, as well as writing style, language and grammar. Following them will make the style and tone of the documentation consistent and clear for the user, and structure and formatting consistent for developers. We derive our guidelines from the AsciiDoc recommended practices, the Kubernetes style guide and the Google developer documentation style guide.

If you are wondering about how to write, structure or format something and what you are looking for is not covered on this page, please consult any of the resources linked above.

Highlights

  • Use PascalCase for API objects. Do not use code style (i.e. ConfigMap not ConfigMap).

  • Use code style for commandlinetools (kubectl, stackablectl), commandline snippets and filenames.

  • Use asterisks for unordered lists.

  • Write a single sentence per line.

  • Use second person: "you" instead of "we".

  • Use sentence case for headings.

File names

We follow Googles recommendations on URL structure. This means we use hyphens (-) instead of underscores (_) in URLs.

Existing files with underscores can be renamed, use Antora page aliases when renaming a file to ensure that old links to the file still work.

Keep file names stable, that means don’t add experimental or similar to the filenames, as otherwise the file name would have to change once a feature matures.

Overall structure: AsciiDoc recommended practices

We rely on the AsciiDoc recommended practices for the overall layout and formatting of the AsciiDoc documents that make up the documentation. Here are the most important parts:

Also - but these recommendations are fairly obvious - use the .adoc extension for AsciiDoc files, use asymmetric Atx-style for section headings, use only four characters for block delimiters.

Read the AsciiDoc recommended practices for more.

Add a :description: to every page. It should have 130 to 150 characters and describe the contents of the page. The description is used by search engines in the search result snippets.

Formatting: Kubernetes style guide

Since the Stackable Data Platform is built on Kubernetes, the resources mentioned in our documentation are very similar to the ones mentioned in the Kubernetes documentation, so we follow the Kubernetes style guide for formatting of code, Kubernetes resources and objects. Some examples:

Code blocks (scripts, console instructions)

For scripts and source code blocks, use this syntax:

[source,yaml] (1)
----
spec:
  command: | (2)
    some-command --with-long-option 'my-option' (3)
----
1 Put the language here, i.e. bash or yaml to get appropriate syntax highlighting.
2 Indent 2 spaces to save horizontal space when applicable.
3 Use long options for shell script flags, as they are easier to understand. Use your own judgment; common ones like rm -rf can still be short flags.

For console instructions, which might include example output:

[source,console] (1)
----
$ echo 'Hello World' (2)
Hello World (3)
----
1 Use console for the highlighting setting.
2 Prefix the command line with the dollar sign ($) so that when the reader clicks the 'Copy' button, only the command-lines are copied.
3 Do not prefix output lines, to prevent the lines from being copied.

More information on code blocks in the Antora documentation.

Tone and writing style: Google developer documentation style guide

For overall tone, writing style, language and grammar the Google developer documentation style guide is a good resource of guidelines. Some highlights:

The Google guide also includes it’s own list of highlights.

Lastly, these are guidelines and not strict rules to follow. Use your own judgement to clearly communicate and explain - after all this is what documentation is about.

Images

Please include an alt text when embedding images. The alt text should describe what can be seen on the picture, to make the documentation more accessible.

CRD documentation

In general, follow the other guidelines. In particular, use PascalCase for API objects and code style for object properties. Start doc strings with an uppercase letter and finish with a period.

If you want to link to a page like this one:

https://docs.stackable.tech/home/stable/concepts/authentication

use the placeholder:

DOCS_BASE_URL_PLACEHOLDER/concepts/authentication

When the CRD gets generated, the placeholder will be replaced with a correctly versioned link to the docs.

Apache product name usage guide

The Apache product name usage guide defines how to refer to Apache products correctly. Essentially, it must be clear that a product belongs to Apache, and also that i.e. Stackable operators are not official Apache operators. The first mention of a product needs to be the full name, i.e. "Apache Spark" instead of just "Spark". Also, the first mention of an operator should be "Stackable operator for Apache Spark"; subsequently you can say "Spark operator" if it is clear that the Stackable operator for Apache Spark is meant.