...

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 ?
• Do not manually add ToC
• Do not use H1 (#) headers
• Start headings with H2 (##)

  Things decided

  • • 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. 

  ...