Developer Documentation Structure ================================= // please don't remove the //word: comments [grid="all"] `------------`----------------------- *State* _Draft_ *Date* _Mon Aug 2 18:03:25 2010_ *Proposed by* Cehteh + Ichthyo ------------------------------------- ******************************************************************************** We describe here how to bring the Lumiera Developer Documentation into an simple yet systematic structure. Previously we accumulated a lot Documentation which ended in quite a few different places. This will gradually be tidied up. ******************************************************************************** Description ----------- //description: add a detailed 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 link:{ldoc}/user/intro/intro.html[Lumiera from Outer Space], which outlines our vision and the fundamental concepts. . there is a section holding our link:{ldoc}/design/[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 link:{ldoc}/technical/overview.html[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 link:{ldoc}/technical/[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 link:{rfc}/[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 link:{ldoc}/technical/howto/[developer HOWTOs and tutorials] . the documentation of technical details is always kept close to the actual source - file level link:{doxy}/[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. - link:{doxy}/classes.html[class level Doxygen] comments serve as definition and summary Tasks ~~~~~ // List what would need to be done to implement this Proposal in a few words: * 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. ([green]#✔ done#) * The 'proc' tiddlywiki is a bit special, we need a plan how to integrate this. [red yellow-background]#TBD# * Create a facility to support the cross-linking between the various kinds of documents [yellow-background]#WIP# Pros ^^^^ // add just a fact list/enumeration which make this suitable: 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 ^^^^ // fact list of the known/considered bad implications: 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 ------------ //alternatives: explain alternatives and tell why they are not viable: - 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 --------- //rationale: Describe why it should be done *this* way: 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. //Conclusion //---------- //conclusion: When approbated (this proposal becomes a Final) // write some conclusions about its process: Comments -------- //comments: append below * 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 3^rd^ 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' ~~ .State -> Draft 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' ~~ //endof_comments: