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.


  • 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

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:

Read the AsciiDoc recommended practices for more.

Formatting: Kubernetes style guide

Since the Stackable Data Platform ist 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:

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.

Bonus: Google search URL structure best practices

Google recommends a URL structure, which is to use hyphens (-) instead of underscores (_) in URLs. So we should aim to create our files with hyphens too. You can use Antora page aliases to rename a page.