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:
