Meetings2012-01-18 » History » Version 5
Version 4 (S. Wrede, 01/18/2012 12:33 PM) → Version 5/7 (S. Wrede, 01/18/2012 12:35 PM)
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)
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)