Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

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. 

...