...

With the listed observations and described proposals we would start the discussion of how we should continue in the documentation project. We strive for are aiming an aligned view on the fields of improvement improvements and their prioritization.

...

• 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 the doc project

• analyse existing Wiki content
  • TODO: check assessment of Eric Debeau
  • TODO: statistics to show status of doc (outdated, incomplete, missing, ...)
• mark existing Wiki pages which are not yet migrated to RTD
• delete existing Wiki pages which are migrated to RTD ?
• define & implement QA process
• update "Contribution" chapters in Wiki and RTD depending on the results of this activity

For content in responsibility of the (sub)projects

• analyse existing Wiki content
• mark existing Wiki pages which are not yet migrated to RTD
• OPT: delete existing Wiki pages which are migrated to RTD
• define & implement QA process

To be discussed

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

...

  How can "we" incentivize "good" documentation?

...

Related Tickets

...

Document History

2019-12-10 Initial doc based on the (modified) mindmap. Alignment to be done.

...