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

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:

secondary colors generated from them are:

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