...
We strive for an aligned view on the fields of improvement and prioritization.
Challenges
Content
ONAP Software (Wiki, RTD)
...
- approx. 1500 build errors (@RTD only, elalto-verify-13.11.2019)
- warnings are ignored
- failed builds are not recognized
- currently one large build which includes all project doc as submodules
- expertise for doc tooling & process is no longer available
- no QA in the release process
Proposals
Create and approved guidelines for ...
...
- doc can be easily searched and filtered
- easy understandable overall structure of chapters and subchapters
- clearly adressing the type of readership (user, developer, admin, manager ...)
- RTD & sphinx theme
- doc must be appealing to the readership
- well defined set of fonts and colors
Approach
For content in responsibility of doc project
...
- TODO: search for an expert in tooling / doc writing that can support
- TODO: support from LF?
- TODO: evaluate tooling and best-practice process for open source documentation and increase acceptance of developers
- TODO: reactivate / update doc team liaisons (as we had it in earlier times)?
- PROPOSAL: Complete restart with the above discussed QA processes in place to build up a new documentation and using only validated / approved and therefore valid content. Even if we are expecting, that the upcoming doc releases will be incomplete or empty in large areas in the beginning.
Questions
- What is the value of more and more ONAP features without having them - and other, important basics - not well documented?
...
- How can we incentivize "good" documentation?
...
Document Versioning
2019-12-10 Initial doc based on the (modified) mindmap. Alignment to be done.
...