|
| 1 | += Documentation style guide |
| 2 | +:page-aliases: style_guide.adoc |
| 3 | + |
| 4 | +:asciidoc-recommended-practices: https://asciidoctor.org/docs/asciidoc-recommended-practices[AsciiDoc recommended practices] |
| 5 | +:kubernetes-style-guide: https://kubernetes.io/docs/contribute/style/style-guide/[Kubernetes style guide] |
| 6 | +:google-style-guide: https://developers.google.com/style/[Google developer documentation style guide] |
| 7 | + |
| 8 | +This page provides guidelines on how to write documentation for the Stackable platform. |
| 9 | +The guidelines cover overall document structure, text appearance and formatting, as well as writing style, language and grammar. |
| 10 | +Following them will make the style and tone of the documentation consistent and clear for the user, and structure and formatting consistent for developers. |
| 11 | +We derive our guidelines from the {asciidoc-recommended-practices}, the {kubernetes-style-guide} and the {google-style-guide}. |
| 12 | + |
| 13 | +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. |
| 14 | + |
| 15 | +== Highlights |
| 16 | + |
| 17 | +- Use PascalCase for API objects. Do not use `code style` (i.e. ConfigMap not `ConfigMap`). |
| 18 | +- Use `code style` for commandlinetools (`kubectl`, `stackablectl`), commandline snippets and filenames. |
| 19 | +- Use asterisks for unordered lists. |
| 20 | +- Write a single sentence per line. |
| 21 | +- Use second person: "you" instead of "we". |
| 22 | +- Use sentence case for headings |
| 23 | + |
| 24 | +== Overall structure: AsciiDoc recommended practices |
| 25 | + |
| 26 | +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: |
| 27 | + |
| 28 | +- https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[Write one sentence per line], i.e. do not use fixed length line breaks. This has multiple advantages outlined in the linked page, among them easier diffing in source control, easier swapping of sentences and avoiding reflow when changing a subsection of a paragraph. |
| 29 | +- https://asciidoctor.org/docs/asciidoc-recommended-practices/#document-attributes-i-e-variables[Use document attributes (variables) to improve text flow], especially for URLs. |
| 30 | +- https://asciidoctor.org/docs/asciidoc-recommended-practices/#lists[Use asterisks for unordered lists]. |
| 31 | + |
| 32 | +Also - but these recommendations are fairly obvious - https://asciidoctor.org/docs/asciidoc-recommended-practices/#document-extension[use the `.adoc` extension for AsciiDoc files], https://asciidoctor.org/docs/asciidoc-recommended-practices/#section-titles[use asymmetric Atx-style for section headings], https://asciidoctor.org/docs/asciidoc-recommended-practices/#delimited-blocks[use only four characters for block delimiters]. |
| 33 | + |
| 34 | +Read the {asciidoc-recommended-practices} for more. |
| 35 | + |
| 36 | +== Formatting: Kubernetes style guide |
| 37 | + |
| 38 | +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: |
| 39 | + |
| 40 | +- https://kubernetes.io/docs/contribute/style/style-guide/#use-upper-camel-case-for-api-objects[Use PascalCase for API objects] such as ConfigMap or KafkaCluster |
| 41 | +- https://kubernetes.io/docs/contribute/style/style-guide/#use-italics-to-define-or-introduce-new-terms[Use _italics_ to define or introduce new terms] |
| 42 | +- https://kubernetes.io/docs/contribute/style/style-guide/#use-code-style-for-filenames-directories-and-paths[Use `code style` for filenames, directories and paths] |
| 43 | +- https://kubernetes.io/docs/contribute/style/style-guide/#use-code-style-for-object-field-names-and-namespaces[Use `code style` for object field names and namespaces] |
| 44 | +- https://kubernetes.io/docs/contribute/style/style-guide/#use-normal-style-for-string-and-integer-field-values[Use normal style for string and integer field values] |
| 45 | +- https://kubernetes.io/docs/contribute/style/style-guide/#use-code-style-for-kubernetes-command-tool-and-component-names[Use `code style` for command line tools] such as `stackablectl` |
| 46 | + |
| 47 | +== Tone and writing style: Google developer documentation style guide |
| 48 | + |
| 49 | +For overall tone, writing style, language and grammar the {google-style-guide} is a good resource of guidelines. |
| 50 | +Some highlights: |
| 51 | + |
| 52 | +- https://developers.google.com/style/tone[Be conversational and friendly] |
| 53 | +- https://developers.google.com/style/person[Use second person]: "You" rather than "we" |
| 54 | +- https://developers.google.com/style/voice[Use active voice] |
| 55 | +- https://developers.google.com/style/capitalization[Use sentence case for headings] |
| 56 | +- https://developers.google.com/style/future[Avoid talking about future features] |
| 57 | +- https://developers.google.com/style/timeless-documentation[Timeless documentation] |
| 58 | + |
| 59 | +The Google guide also includes it's own list of https://developers.google.com/style/highlights[highlights]. |
| 60 | + |
| 61 | +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. |
| 62 | + |
| 63 | +== Bonus: Google search URL structure best practices |
| 64 | + |
| 65 | +Google recommends a https://developers.google.com/search/docs/crawling-indexing/url-structure[URL structure], which is to use hyphens (`-`) instead of underscores (`_`) in URLs. |
| 66 | +So we should aim to create our files with hyphens too. |
| 67 | +You can use https://docs.antora.org/antora/latest/page/page-aliases/[Antora page aliases] to rename a page. |
0 commit comments