108 lines
3.7 KiB
Text
108 lines
3.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 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:
|