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:

Use PascalCase for API objects such as ConfigMap or KafkaCluster
Use italics to define or introduce new terms
Use code style for filenames, directories and paths
Use code style for object field names and namespaces
Use normal style for string and integer field values

For writing style, language, grammar and tone guidelines we refer to the Google developer documentation style guide. Some highlights:

Be conversational and friendly
Use second person: "You" rather than "we"
Use active voice
Use sentence case for headings

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.