[TYPO3-doc] Experiences with ReSTructured Text

[Jigal van Hemert]

Hi,

On 6-9-2011 22:11, jean-sebastien_gervais at ssss.gouv.qc.ca wrote:
> Hello list,
>
> Thank you Francois for this helpful summary of the recent debate between
> the docbook format and ReST.
>
> The way I understand it, the main features needed are :
>
> - Ease of use / Learning Curve,
> - Readability
> - Exportable formats / Migration
> - Styling policy
> - Images support
> - Crosslinking
> - Translation
> - Support
>
> While both ResT and Docbook do have their own strengths and benefits, the
> translation part with Pootle is a major issue IMO. And besides, we already
> have tools that can do it all.
>
>
> Ease of use / Learning Curve
> =========================
> Everyone on this list uses it. Extension developers use it too.

Even better: everybody who likes to do any documentation on TYPO3 uses it.

> Readability
> ==========
> The text editor is WYSIWYG, styling can be defined for all documents for
> both editing and or export

Indeed. An extension could be made which defines the available styles 
and makes the editor reflect those styles.

> Exportable formats / Migration
> =========================
> I'm pretty sure there is already support for what we need : HTML, PDF, etc.

Challenge here is that for the reference part of the documentation I 
would like to see a system with a more semantic mark-up. Maybe this can 
be arranged and the transformations can take care of different 
presentations.

> Translation
> ==========
> Pootle could be used if it tolerates usual HTML semantics, otherwise,
> having alternate contents for each paragraph / tables / images should solve
> the issue. And with a proper workflow, we can achieve similar results to
> what Pootle can do.

There is translation support built in, but it will be a challenge to 
have support for a centralized translation mechanism (pootle). 
l10nmanager can be extended with xliff support, which can make this 
possible somehow.

> Workflow / Access Right
> =====================
> Supports accounts, groups, and fine security granularity.

This implies that documentation should be created on a documentation 
server? Each contributor has a BE account with limited access?
Hmm... it would be a good thing to make creating documentation possible 
without internet access (intranet server, localhost,...). In reality not 
everybody who uses TYPO3 has constant and complete internet access.

> I know it may sound crazy, but with proper planning, anything can be done.
> And just think about the credibility impact that would have on the
> community. Have you seen other serious CMS using their own CMS for
> documentation? I believe TYPO3 is mature enough and can make that leap
> ahead the other CMS.

It's certainly a good thing if TYPO3 would be used to create the TYPO3 
documentation.

> The only drawback is it will need a bit more efforts than using openOffice
> / docbook / ReST but I'm pretty sure it will pay off over time.

All solutions need efforts to make a good work-flow; in 
OpenOffice.org/LibreOffice documents you could use styling to mark 
various elements, but these need to be parsed; docbook lacks an easy 
editor (a WYSIWYG web based XML editor like xopus [1] would be nice, but 
it is licensed); ReST lacks semantic mark-up.

[1] http://www.xopus.com

-- 
Kind regards / met vriendelijke groet,

Jigal van Hemert.