Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 9 Next »


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

  • 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?
  • When we have links at the bottom of our pages?
  • When to have a "this page is draft note"?
  • Do we enable "TBD"s in the documentation?
  • Do we allow only K8s, both Kubernetes and K8s or only Kubernetes?
  • Common way for notes and alerts using the example from here: https://www.docsy.dev/docs/adding-content/shortcodes/#reuse-documentation ?

Things decided

  • Do not manually add ToC
  • Do not use H1 (#) headers
  • Start headings with H2 (##)

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/







  • No labels