Merge pull request #183 from Kuadrant/style-guide

Add some contributing notes and a style guide

CONTRIBUTING.md

@@ -0,0 +1,13 @@
+The site configuration and navigation layout are defined in [./mkdocs.yml](./mkdocs.yml).
+The navigation sections follow the [Diátaxis framework](https://diataxis.fr/), with four main areas:
+
+- Concepts (known as 'Explanation' in Diátaxis)
+- APIs & Reference
+- Tutorials
+- Guides
+
+When adding new documentation, take a moment to consider which area the document belongs to.
+You can use the [Diátaxis compass](https://diataxis.fr/compass/) to help answer that question.
+If you are unsure, raise an issue, create a PR anyways to invite discussion, or reach out on the [#kuadrant](https://kubernetes.slack.com/archives/C05J0D0V525) slack channel.
+
+When writing content, refer to the [./style_guide.md](./style_guide.md) for writing style guidelines, tips and examples.

README.md

@@ -4,6 +4,10 @@
 
 This repository contains documentation for Kuadrant, built using MkDocs and the `mike` plugin for multi-versioning. You can run and build these docs using Docker/Podman or by installing MkDocs locally.
 
+## Contributing
+
+See [./CONTRIBUTING.md](./CONTRIBUTING.md)
+
 ## Using Docker/Podman
 
 ### Running the Docs with Docker

style_guide.md

@@ -0,0 +1,101 @@
+# Style Guide
+
+## Framework
+
+Follow the [Diátaxis approach](https://diataxis.fr/) when you think about and work on new documentation. 
+This approach helps you decide on what kind of documentation to write and how to write it well. 
+
+## Voice
+
+Documents should be written mainly in a combination of "second person" and "active voice", depending on the context.
+
+### Second Person
+
+Address the reader directly, often using "you".
+For example, "You need to create a HTTPRoute",
+rather than saying "An HTTPRoute needs to be created by you."
+
+### Active Voice
+
+The subject of the sentence performs the action.
+For example, "The Gateway controller processes the HTTPRoute to establish routing rules",
+rather than saying "The HTTPRoute is processed by the Gateway controller to establish routing rules"
+
+## Tense
+
+Use present tense, unless the meaning is better conveyed in future or past tense.
+For example, "This command starts the operator"
+rather than "This command will start the operator"
+
+## Language
+
+Use simple and direct language. Avoid unnecessary phrases, such as saying 'please'.
+For example, use "To create a ReplicaSet,..." instead of "In order to create a ReplicaSet, ...".
+Another example, use "View the pods." instead of "With this next command, we'll view the pods".
+
+## Avoid jargon and idioms
+
+Some readers may not speak English as a primary language. Avoid jargon and idioms to help them understand better.
+For example, use "Internally,..." instead of "Under the hood,...",
+or "Create a new cluster." instead of "Spin up a cluster."
+
+## Avoid time sensitive statements
+
+Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information.
+An exception to this would be mentioning the deprecation (and potential eventual removal) of some API.
+
+Avoid statements that will soon be out of date.
+An indication of this is words like "currently" and "new." A feature that is new today might not be considered new in a few months.
+
+For example, use "In version 1.0, ..." instead of "In the current version, ...".
+
+## Avoid words that don't add value
+
+Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value.
+
+## Images
+
+Avoid the overuse of images and screenshots as they can be a pain to maintain.
+
+## Characters
+
+Avoid the use of unusual characters, for example Unicode numbering and emojis.
+
+## Grammar
+
+* Start sentences with capital letters and end with . or :
+* Products, projects, and tools should be capitalised i.e Kuadrant, Authorino, Limitador etc
+
+## Inline Blocks, Notes & Warnings
+
+To highlight some content like blocks, notes or warnings, use the correct formatting as per https://squidfunk.github.io/mkdocs-material/reference/admonitions/#inline-blocks
+
+For example:
+
+````markdown
+```markdown
+!!! note
+
+    This method currently only works if the Gateway is provided by Istio, with service mesh capabilities enabled across the cluster.
+```
+````
+
+## Code Blocks
+
+For code blocks preface the language in the code block as per https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#usage
+
+For example:
+
+````markdown
+```bash
+kubectl get deployments -n kuadrant-system
+```
+````
+
+## Numbering in lists
+
+Avoid the overuse of numbering. It allows for docs to be updated much easier in the future.
+
+## Environment Variables
+
+Environment variables should be capitalised and use 'KUADRANT_' at the start, for example, `KUADRANT_GATEWAY_NS`, unless they are already defined environment variables for existing tools and services.