Meetings2012-01-18 » History » Version 4
S. Wrede, 01/18/2012 12:33 PM
1 | 1 | S. Wrede | h1. Meetings 2012-01-18 |
---|---|---|---|
2 | 1 | S. Wrede | |
3 | 1 | S. Wrede | Single topic: Documentation |
4 | 1 | S. Wrede | |
5 | 1 | S. Wrede | h2. Goals |
6 | 1 | S. Wrede | |
7 | 1 | S. Wrede | * Generate different views for different stakeholders |
8 | 1 | S. Wrede | |
9 | 1 | S. Wrede | h2. Insights from short literature survey: |
10 | 1 | S. Wrede | |
11 | 1 | S. Wrede | * Documentation artefacts which are close to source code (commits, tests, comments, API docs, ...) are easier kept up-to-date and thus well maintained |
12 | 1 | S. Wrede | * Big-picture / architecture information is important even if outdated |
13 | 1 | S. Wrede | * Consider your readers! What are those? Devs, Users, Architects? |
14 | 2 | S. Wrede | |
15 | 2 | S. Wrede | h2. Results |
16 | 2 | S. Wrede | |
17 | 2 | S. Wrede | * Use CIT catalogue as module guide (cf. Parnas) |
18 | 2 | S. Wrede | * Add new content type @tutorial@ for overarching documentation modules |
19 | 2 | S. Wrede | ** this will allow us to model dependencies to software etc. directly using the mechanisms of the CIT catalogue |
20 | 2 | S. Wrede | ** tutorials will refer to our sphinx generated documentation |
21 | 2 | S. Wrede | * Views are important |
22 | 2 | S. Wrede | ** required for catalogue *and* our generated documentation |
23 | 3 | S. Wrede | * Sphinx documentation guidelines |
24 | 3 | S. Wrede | ** Examples should be largely self-explanatory as they will be included directly in the documentation |
25 | 3 | S. Wrede | ** Concept explanation will be short in favor of more elaboration in the language specific examples |
26 | 3 | S. Wrede | ** Important differences shall however be marked in the sphinx docs |
27 | 3 | S. Wrede | ** Component descriptions shall be language independent (at least for RSB) |
28 | 3 | S. Wrede | ** Man-page generation is an open issue |
29 | 4 | S. Wrede | ** Glossar seems very useful but should be available from a centralized documentation |