LUMIERA.clone/doc/devel/rfc/DeveloperDocumentationStructure.txt

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' ~<prg@ichthyostega.de>~


.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' ~<prg@ichthyostega.de>~


//endof_comments: