...
Note! This is not a documentation guide, but a list of things related to the creation of one.
Things to decide
- US or British English?
- Do we have an option to describe the output of commands inline or they are always in a code block?
- `` should be used for commands, file names, but not for IP addresses
- Do we use the console code block of we use bash instead?
- Use `bash for shell commands and output
- Use `yaml for YAML, `json for JSON
- Use `golang for Go
- Use \`\`\` without defining the type of the block only in exceptional cases
- When we have links at the bottom of our pages?
- Use the default behavior
- When to have a "this page is draft note"?
- When someone is working on the content
- Do we enable "TBD"s in the documentation?
- Nope. We should not have TBDs
- Do we allow only K8s, both Kubernetes and K8s or only Kubernetes?
- Use only Kubernetes
- Do we allow inline links, [] kind of links and/or footnotes?
- Both ways can be used, but it is recommended to use inline links
- Max mine length?
- Anything goes
- Forcing newline before and after lists?
- Anything goes
Things decided
- US English
- Do not manually add ToC
- Do not use H1 (#) headers
- Start headings with H2 (##)
- Common way for notes and alerts using the example from here: https://www.docsy.dev/docs/adding-content/shortcodes/#reuse-documentation ?
- For simple notes use "{{% alert title="Note" color="primary" %}}"
- For warnings use "{{% alert title="Note" color="warning" %}}"
Framework
Currently we use the Hugo/Docsy/Netlify framework to generate and host the documentation. This section collects the pros and cons of the different frameworks.
...