Ichthyostega
051cb31e28
The RfC documents were written to complement discussions of the Lumiera developers; yet since the time where ''Ichthyo'' is working basically alone on the project, this kind of discussions have ceased. During the following years, some ideas promoted by the existing RfC documents became rather detached from the actual state of development in the code base. Many of the existing RfC documents require some commentary to place them into context, and some of the decisions taken in the early stage of the project should be **re-assessed**. This includes the decision to reject some proposals, which initially might have seemed desirable, yet could not be reconciled with the understanding of the matter and topic in question, as was gained through the ongoing analysis and development.
208 lines
9.7 KiB
Text
208 lines
9.7 KiB
Text
Developer Documentation Structure
|
|
=================================
|
|
|
|
// please don't remove the //word: comments
|
|
|
|
[options="autowidth"]
|
|
|====================================
|
|
|*State* | _Final_
|
|
|*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 in a way omitting 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
|
|
link:{ldoc}/technical/overview.html[»Lumiera: The inner Core«]
|
|
document or write separate documentation pages or RFC's. ([green]#✔ done#)
|
|
* The »Renderengine« TiddlyWiki is a bit special, we need a plan how to integrate this.
|
|
* Create a facility to support the cross-linking between the various kinds of documents
|
|
[red yellow-background]#TODO#
|
|
|
|
CAUTION: this issue with stable cross-links
|
|
-> link:{rfc}/WebsiteSupportMarkup.html[remains a concern]
|
|
|
|
|
|
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 approvedd (this proposal becomes a Final)
|
|
// write some conclusions about its process:
|
|
This RfC had been started initially by _Cehteh_ to propose a _simple structure_ --
|
|
the ensuing discussion however showed that our documentation is already structured
|
|
in a mostly consistent way, which just happens to be not that simple. Some confusing
|
|
redundancies could be removed, as result from that discussion. _Ichthyo_ then edited
|
|
and extended the original RfC to reflect the existing structure.
|
|
|
|
A serious problem is posed by the rather tedious procedure to define cross-links in the
|
|
Asciidoc based web content. link:{rfc}/WebsiteSupportMarkup.html[Another RfC] was created
|
|
to discuss these problems in detail, leading to a solution proposal, which unfortunately
|
|
was never implemented (due to lack of developer capacity). This _somehow transitory_
|
|
situation had the (adverse) effect that most detailed technical content was authored
|
|
within the Development TiddlyWiki.
|
|
|
|
These remaining problems do not seem to be related to the _structure_ of the documentation
|
|
however, which seems to fulfil its purpose. So this RfC now counts as de-facto standard.
|
|
|
|
|
|
|
|
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
|
|
a 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, in fact I consider the RFCs relevant and want to retain this formalism)
|
|
- 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 at 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, waiting to be discovered)
|
|
|
|
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>~
|
|
|
|
|
|
.State -> Final
|
|
I am using this structure since several years now, without encountering any
|
|
serious mismatch or incompatibility. The situation with the cross-linking
|
|
generator, which still remains to be implemented, is obviously some kind
|
|
of impediment, since it prevents me from migrating more mature content
|
|
from the TiddlyWiki into the documentation section of the website.
|
|
|
|
Furthermore, I should notice, as a limitation, that I am the _only one_ to
|
|
use this structure actively -- so the fact that I feel comfortable with
|
|
the arrangement should be taken with a grain of salt. Yet, on the other
|
|
hand, we have meanwhile a massive body of information structured
|
|
this way, so that it can be considered more than
|
|
just a ``proposal for discussion''
|
|
|
|
Ichthyostega:: '2025-09-20'
|
|
|
|
//endof_comments:
|