Documentation team


What is this?

This page contains information related to the Nephio documentation. This is not  the documentation itself. The documentation lives in https://docs.nephio.org/

Documentation guide

Note! This is not a documentation guide, but a list of things related to the creation of one.

Things to decide

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

FrameworkProsCons
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: 

secondary colors generated from them are:

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