| State | Draft |
| Date | Mon Aug 2 18:03:25 2010 |
| Proposed by | Cehteh + Ichthyo |
Description
The Lumiera (developer) documentation shall be organised in the following way:
-
the documentation sources are kept within the main source tree, except for heavyweight binary content (e.g. videos)
-
using a simple git hook script, these contents are automatically published at the Lumiera.org website
-
documentation is organised into several tiers:
-
an entry level »Intro« is given within the document Lumiera from Outer Space, which outlines our vision and the fundamental concepts.
-
there is a section holding our design documents. Deliberately, these are written so to omit any technicalities, which keeps them valid as the technology evolves.
-
the entrance to the technical documentation is formed by The inner Core document. Here, the interested reader finds a round trip visiting each subsystem and each globally relevant facility, without going too much into details. This reading should provide a fair understanding of the primary parts of the application and their interplay. Each section should provide links into the relevant technical detail documentation.
-
the extensive technical documentation is comprised of several bodies of information existing side by side
-
there is a hierarchy of written documentation to explain the workings of subsystems and components. Typically, these writings emerge from working notes and design drafts.
-
crucial decisions and the results of discussions are captured in a formalised style within our RfC documents
-
often, a chosen design is the result of extensive discussions, which can be comprehended by reference to mailing list threads and IRC transcripts
-
there is a section with developer HOWTOs and tutorials
-
-
the documentation of technical details is always kept close to the actual source
-
file level Doxygen comments serve as overview and explanations of key abstractions and components.
-
unit tests are often written in a “narative” fashion and are considered part of the detailed specification.
-
class level Doxygen comments serve as definition and summary
-
-
Tasks
-
Go over the existing content and the remainder of the asciidoced tiddlywikis, integrate this content either in directly into the "Lumiera: The inner Core" document or write separate documentation pages or RFC’s. (✔ done)
-
The proc tiddlywiki is a bit special, we need a plan how to integrate this. TBD
-
Create a facility to support the cross-linking between the various kinds of documents WIP
Pros
Much easier entry to the whole developer documentation. Reading the »Inner Core« document should be sufficient to get a good idea about the Lumiera design and layout. All details are linked from there and thus easily findable.
Cons
There are some open ends yet, Doxygen for example doesn’t integrate so nicely. Same for the mailing list archives and the issue tracker. Other parts like the UML model are not decided yet; moving the other existing content over and establishing the necessary cross-links requires quite some work.
Alternatives
-
Spring 2010 we discussed and decided an overall website and documentation structure. We could just stick to that and hook up everything into this structure
-
use the extended Doxygen facilities to build the whole documentation entirely within the source files
-
use an external Content Management System or Wiki for documentation
-
write our own documentation system
Rationale
This approach fits nicely into our overall infrastructure and the way we wanted to do things. Using git and asciidoc mostly, making the developer documentation part of the source tree and reasonable easy available/maintainable to developers.
Comments
-
The general idea of having three levels, with The Inner Core as entry point, looks OK for me.
-
beyond that — we had a detailed discussion about the overall website structure, which includes the documentation. Why should we overthrow these results now and re-start the discussion? Lets just stick to this agreed on structure!
-
especially I don’t like the way this proposal tries to squeeze everything into an completely uniform structure. It is simply not true that the RFCs are just the second level, and doxygen would cover the 3rd level. Look at the existing documentation to see why.
-
RFCs are a kind of document, not a hierarchy level. Indeed, our existing RFCs span all three hierarchy levels, and this is OK so and should remain this way. (And yes, I like the RFCs much and want to retain them)
-
RFCs are well suited to topics requiring discussion and agreement by the whole core developer team. I see no point in pseudo-RFC-ing the individual design decisions only relevant for an isolated part of the application and without any potential for discussion.
-
similarily, in the TiddlyWiki, besides just working notes (“extended brain”) you’ll find finished text pages belonging to all different levels, from very high-level conceptual down to explanation of technical details, with cross references and tags for categorisation (and this will be retained when asciidocing the content).
-
-
so my conclusion is rather having one overview text, and then the split into conceptual and technical documentation, each of which has a separate sub structure not necessarily congruent to the structure on the other half. RFCs, UML model and doxygen are just separate and consistent bodies of documentation and can be referred to from the main documentation. (I agree with the observation regarding permanent links into doxygen. But I can’t imagine there isn’t some existing solution to this problem)
- Ichthyostega
-
2010-10-15 <prg@ichthyostega.de>
Now I’ve edited this RfC to reflect our actual documentation structure more closely. In the end, the differences to Cehteh’s original proposal turned out to be rather minor points. Most notalbly, we couldn’t agree on building the second tier solely out of RfCs. In fact, there exists already a whole body of documentation in textual form, which is inherentely structured.
- Ichthyostega
-
Mo 09 Sep 2013 01:01:25 CEST <prg@ichthyostega.de>