136 lines
5.7 KiB
Text
136 lines
5.7 KiB
Text
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:
|