...

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?
  ToC or not ToC?
  • 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. 

  Framework	Pros	Cons
  Hugo/Docsy/Netlify	We have a working framework Other cloud native projects are using the same Netlify is really easy to use Versioning support is built in to the framework Multi language support if built in to the framework	Using Netlify to publish means that we do not control the full pipeline of building and publishing the docs Both Hugo and Docsy are sensitive to versions. There are lots of incompatibility issues. There is a limit of traffic and biulds for the free open source tier of Netlify
  MKdocs	Other projects, like Kubenet are using it
  Hugo/Docsy/own server	We have a full control over the build and publication of our documentation We do not depend on the goodwill of Netlify for the free service	It is not clear if we have a server to use We need to build the whole pipeline to build and publish the documentation

  
  

  Colors

  These are the primary colors of the Nephio logo: 

  Image Added

  secondary colors generated from them are:

  Image Added

  Also available here: https://color.adobe.com/Nephio-secondary-colors-color-theme-0bbcdea2-0533-4ab3-812f-f752f30b5b40/