...
- US or British English?
- Do we have an option to describe the output of commands inline or they are always in a code block?
- Do we use the console code block of we use bash instead?
- ToC or not ToC?
- When we have links at the bottom of our pages?
- When to have a "this page is draft note"?
Things decided
- Do not manually add ToC
- Do not use H1 (#) headers
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:
...