[Typo3-typo3org] TDR concept

[Michael Scharkow]

Robert Lemke wrote:
> Hi folks,
> 
> Michael Scharkow has sent me a first draft of the TDR concept based on his
> thoughts from an earlier thread. I injected my ideas about the TDR and we
> now have a first draft [1] we can use for further discussion.
> 
> We have to take some basic decisions before we go on and before we take that
> decisions we must be aware of the pros and cons. On these points we'd like
> to hear your opinion (of course add more points if you think something is
> missing):
> 
> [A] True import of the source documents into the page tree. 
> Technically this is a bit more work but the big advantage is that you don't
> need any special rendering routines for displaying the documents online. It
> is also the prerequisite for using TIMTAW and the like for editing
> documentation online and then exporting it to OO again.

I'm fine with that. As long as the rendering/import is triggered
automagically when docs are updated, this is a good solution. We only
have to make sure bidirectional conversion works reliably.

> [B] Use the TER for distributing documentation instead of yet another
> repository.
> When we put documentation into the TER side by side with the extension
> files, they will be automatically mirrored and can be accessed through the
> same channels like the extensions. What frontend interface we use for that
> is a different question but behind the scenes I propose using the TER.

Okay, I have some objections to that (note that most of them were
already mentioned before):

1. There's a lot of documentation that is not related to extensions.
Should we really make pseudo-extensions for this. I find doc-only
extensions horrible, the extension list is already long enough.
2. Don't mix code and documentation management, as they have really
different requirements. If we find similar requirements, why not make
shared classes for those cases?
3. If we want a doc-team to manage docs, we should (for security and
ease of use) not have them fiddle with extensions.

But for Roberts argument:
Why can't we make the whole TER functionality general enough and use it
for TDR as well? This would not mean we mix extensions with
documentation, but for distribution, we use two different instances of
class TER, so to speak. Wouldn't this be a useful compromise about using
TER and still separating extensions and documentation?

> [C] Keep everything together on TYPO3.org.
> Instead of creating another subdomain (docs.typo3.org) like I suggested
> earlier, I now think we should keep everything together on TYPO3.org. If
> TYPO3.org is down at some point, documentation is still available via the
> TER (ie. you can download it using the EM, HTTP directly etc.). 
> Additionaly we can create mirror sites for documentation later on and they
> will just render the documents they get through the TER.

I'm pretty indifferent on this issue: If we don't split it up we will
eventually run into some trouble: There could be permission issues (note
that we will have doc-team members as BE users), eventually we will have
to run Openoffice on the server (unless we find a viable alternative,
which I have not until now). But other than that, I don't see any big
problems with that.

> [D] Use XSLT where possible
> If we go for [A], we would make up an TYPO3 XML format which reflects pages
> and (flexible-) content elements. To import a foreign document (like ODT,
> SXW or docbook) we just have to run a transformation and then import the
> TYPO3 native format. The same goes for exporting documents.

This is mainly an issue of "great idea, who has the time/dedication to
do it". It would certainly be desirable to have a standard import/export
format for content as well as whole page trees. But I'd prefer if we
could use a standard XML rather than make yet-another-one. Why can't we
just use native ODT as a format and continue in the vain of Robert's
office-importer (and exporter)?

Greetings,
Michael