Merge documentation and RFCs

.gitignore

@@ -20,6 +20,10 @@ autom4te.cache
 semantic.cache
 tests/,*
 wiki/backups/*
+doc/*.html
+doc/devel/rfc/*.html
+doc/devel/rfc_pending/*.html
 doc/devel/draw/*.png
+doc/user/*.html
 doc/user/lumiera_from_outer_space/*.html
 m4/*

doc/devel/rfc_pending/DeveloperDocumentationStructure.txt

@@ -0,0 +1,136 @@
+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 introductory 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:
+
+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 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:
+
+Spring 2010 we discussed and decided an overall website and documentation structure.
+We could just stick to that.
+
+
+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)
+  -- link:Ichthyostega[] 2010-10-15
+
+//endof_comments: