Robotics Service Bus

h1. Meetings 2012-01-18

Single topic: Documentation

h2. Goals

* Generate different views for different stakeholders

h2. 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?

h2. 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)