Meetings 2012-01-18¶

Single topic: Documentation

Goals¶

• Generate different views for different stakeholders

Insights from short literature survey:¶

• Documentation artefacts which are close to source code (commits, tests, comments, API docs, ...) are easier kept up-to-date and thus well maintained
• Big-picture / architecture information is important even if outdated
• Consider your readers! What are those? Devs, Users, Architects?

Results¶

• Use CIT catalogue as module guide (cf. Parnas)
• Add new content type tutorial for overarching documentation modules
  • this will allow us to model dependencies to software etc. directly using the mechanisms of the CIT catalogue
  • tutorials will refer to our sphinx generated documentation
• Views are important
  • required for catalogue and our generated documentation
• Sphinx documentation guidelines
  • Examples should be largely self-explanatory as they will be included directly in the documentation
  • Concept explanation will be short in favor of more elaboration in the language specific examples
  • Important differences shall however be marked in the sphinx docs
  • Component descriptions shall be language independent (at least for RSB)
  • Man-page generation is an open issue
  • Glossar seems very useful but should be available from a centralized documentation
  • CI server needs to automatically build (and deploy) the generated documentation (otherwise each dev would need to build the whole library stack to build documentation)