[TYPO3-english] Current Documentation format

[Dirk Wenzel]

Hi Francois,
IMHO the lack of fancy styling is not an issue but an advantage. The new 
pages do load as fast as hell and using the search field of the browser 
shouldn't be too difficult.

But I'm concerned that the extension documentation rendered on 
docs.typo3.org seems to be quite outdated. For an extension which I 
updated several times during this week it still shows a version from 
2013-01-29.

Since I don't like using SWX at all (due to the painful editing process 
and the unpredictable result of the rendering) I would prefer using ReST 
from now on. It shouldn't be to expensive to grab any ReST-manual from 
an extension and put it to the new location. Every developer could 
easily point to this place in an stub SXW-document than. This link could 
even be rendered automatically...

Using the current documentation in TER is a pain: too many clicks, too 
many TOC-entries with no content, too many shreddered entries (where 
content of paragraphs landed in TOC). And as a result too many links to 
external pages (fedext.net, browser ...)

BTW: thank you for working on the new documentation : )
Kind regards
Dirk

Am 15.02.13 09:47, schrieb François Suter:
> Hi Thomas,
>
>> I'm just about finishing my first Extbase extension and the only part
>> that's missing is documentation. I've learned, that
>> OpenOffice/LibreOffice format SXW is dead, as well as DocBook, and I've
>> red that ALL of TYPO3 6.0 documentation hast moved to Rest. Looking into
>> forge I notice that all files under the "doc" folder of sysextensions
>> are still in SWX format.
>
> We are in a phase of transition, hence the confusion that you may
> perceive. Indeed all official documentation has been moved ReST. For
> extensions, it is our aim in the near future. The current situation is
> that - if you choose ReST - the link to the documentation will not
> appear in the TER, but it is still geared to detect only
> "doc/manual.sxw". The manual will be rendered on:
>
> http://docs.typo3.org/typo3cms/extensions/
>
> which is unfinished, in the sense that it doesn't have the proper look &
> feel and is unusable for lack of a search/filter feature. This is
> something we are currently working on.
>
> TBH I'm not sure what answer to give you. If you want to be sure that
> the documentation of your extension is available to the widest audience
> possible, stick to SXW. As you can see from the page indicated above,
> all manuals are automatically transformed to ReST. So you could at a
> later stage - pick up that source to officially move your manual to
> ReST, without having to start all over again.
>
> Cheers
>