RFC: new doc structure

doc/devel/rfc_pending/DeveloperDocumentationStructure.txt

@@ -0,0 +1,108 @@
+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 <ct@pipapo.org>
+-------------------------------------
+
+[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: