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)
• Tutorial ideas
  • We will add a new central redmine project for CoR-Lab tutorials with a single SVN
    • contains Sphinx source code for tutorial, each tutorial is independent Sphinx project
    • but also contains tutorial source code (ideally coded against the stable version of available libs)
  • Single CI Job for the generation of all tutorials (only the documentation, responsibility of us)
  • Multiple CI Jobs for testing the tutorial source codes (responsibility of the developers)