[Typo3-typo3org] TER 2.0 - updated concept!

[Robert Lemke]

Hi Michael,

I'll try to give some arguments in favour of including documentation into
the TER, just to make sure we don't miss anything ...

Michael Scharkow wrote:

> 1. If I have a webserver running TYPO3 somewhere, I don't need to
> download documentation with EM because I cannot view it anyway, at least
> I don't know how to read sxw over ssh...

I wrote an extension which allows you displaying SXW-based manuals in the
backend or in a separate window. It currently has some problems with very
big documents like TYPO3 Core APIs but if I solve that, it is a very
comfortable way of reading documentation while you work with an extension.

> 2. To the EM it makes absolutely no difference where you download an
> extension documentation from, so we might as well refer to docs.typo3.org

Yes. But the TER will be mirrored, we don't have a concept for mirroring
docs.typo3.org yet. That is my main point: The whole documentation will be
always available, even if all typo3.org sites are down.

> 3. We can provide a complete infrastructure for documentation on
> docs.typo3.org, including uploading, editing (with Wiki/timtaw/younameit
> once this is possible), conversion to different formats.

We should do that in either case. For the user / developer it won't make it
a difference if the documentation comes from the TER or some other source,
he will be able to read and edit it on docs.typo3.org, even uploading it at
that site wouldn't be a problem.

> 4.  With such a setup, you could not only have a checkbox in EM "dowload
> documentation" but even "download documentation as [sxw|pdf|plaintext]"
> and you fetch only what you need

Does it make sense downloading PDF documentation with the EM? If so, that
could be easily implemented in either case.

> 5. Using extensions for docs would double the number of extensions
> (=more disk space, more traffic, more effort), meaning e.g. that
> extensions.xml is twice as long.

That might be a disavantage. But how big would the extensions.xml be anyway?

> 6. If we package docs in extensions (and I assume you want this to be
> the *only* way to manage docs because doing thing twice is useless), we
> would need need an extension for every doc out there.

Yes, but that could be automized. 

> 7. docs.typo3.org would require access to TER which is completely
> against the policy of splitting stuff up.

docs.typo3.org would just be a supporting mirror for its own purposes. When
documents are uploaded on docs.typo3.org they will be transfered via SOAP
to the main TER, like uploading any other extension.

> 8. Did I mention doc-only extensions suck? Like I don't need emconf.php
> for a stupid oowriter file...

Maybe it's worth investing that extra work if we gain the advantages
mentioned above.

> 9. In which way would docs benefit from TER2, except that I can have
> cool stuff like dependencies, so FTB depends on MTB? Which is, of
> course, very useful to enforce ;)

As I wrote above: The main advantage is that all documentation is at the
same place where its extension is and will be mirrored automatically.

-- 
robert