Documentation style guide

This page provides guidelines on how to write documentation for the Stackable platform.

Style guidelines specify things such as capitalization rules, which format to use for emphasis or how API objects and other components should be styled in the documentation - formatting and "superficial" aspects of text. Grammar, tone and voice guidelines make the documentation consistent across the pages and as clear as possible. These guidelines include using a conversational tone, using second person and active voice.

For formatting text and code, follow the Kubernetes documentation style guide. The Stackable platform is built on Kubernetes and the documentation often refers to Kubernetes API objects, custom resources and snippets of resource specifications, as well as command line snippets to interact with Kubernetes clusters. The Kubernetes documentation style guide specifies how these terms and snippets should be formatted. Some examples:

For writing style, language, grammar and tone guidelines we refer to the Google developer documentation style guide. 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.