Developer Documentation Structure ================================= // please don't remove the //word: comments [grid="all"] `------------`----------------------- *State* _Idea_ *Date* _Mon Aug 2 18:03:25 2010_ *Proposed by* Christian Thaeter ------------------------------------- [abstract] ******************************************************************************** I describe here how to bring the Lumiera Developer Documentation into an simple hierarchical structure. Previously we accumulated a lot Documentation which ended in quite a few different places. This should be tidied up. ******************************************************************************** Description ----------- //description: add a detailed description: I propose to reorganize the developer documentation in the following way: * make a 3 (or more, see below) level documentation structure: 1. The entry level becomes the 'Lumiera: The inner Core' document which shall not go into details but give a hint what everything is made for. This will be the first introductional doc for new developers. 2. second level are the RFC's which descibe the design as planned on a general level, not going (except for some example snippets) into implementation details. 3. the third level is the doxygen documentation which describes what actually got implemented in detail. This can be further split into an external reference and a internal part. We using test-driven-development, our tests are our specifications. This leads to the idea that ideas, design and intentions for tests should be documented there too. In a higher level abstract human written form. I propose to use my pipadoc documentation extractor (that means, writing asciidoc within the code as special comments) for this. Tasks ~~~~~ // List what would need to be done to implement this Proposal in a few words: // * item ... * Go over the old content of the asciidoced tiddlywikis, integrate it either in the "Lumiera: The inner Core" document or write single RFC's for them. * The 'proc' tiddlywiki is a bit special, we need a plan how to integrate this. Possibly making a own document-dir for this, or refactor it in plenty RFC's. This is ichthyos decision. * Decide how to proceed with the UML model Pros ^^^^ // add just a fact list/enumeration which make this suitable: // * foo // * bar ... 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 doesnt integrate nicely, we possibly can't link to single doxygen entities since these have no permanent link (to my understanding, to be investigated). Other parts like the UML model are not yet decided and moving the other existing content over needs some (not really much) work. Alternatives ------------ //alternatives: explain alternatives and tell why they are not viable: Wait for a miracle that our docs become well organized on its own. 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 deveoplers. //Conclusion //---------- //conclusion: When approbate (this proposal becomes a Final) // write some conclusions about its process: Comments -------- //comments: append below //endof_comments: