[TYPO3-core] Migrating system extension manuals to ReStructured Text

[François Suter]

Hi all,

The topic of migrating the system extension manuals to ReST was already 
mentioned in the past, but we are now set to actually do it. In 
particular the Documentation Team discussed it with Ernesto (as 6.2 RM) 
in its latest meeting. On Friday, I also met with Xavier and Dominique 
Feyer who were interested in the topic. In particular Xavier has already 
done quite some work with ReST-based documentation and TYPO3 
integration. The idea was to brainstorm about the topic and submit a 
first draft of a plan in this list for discussion. So here we go:

1) over the next few weeks, I'll take care of migrating existing system 
extension manuals to ReST. To give you an idea, here are the sysext that 
have manuals (some being very short, but still):

- css_styled_content
- dbal
- felogin
- form
- linkvalidator
- openid
- recycler
- rsaauth
- rtehtmlarea
- saltedpasswords
- scheduler
- sys_action
- taskcenter
- workspaces

We have tools to transform OpenOffice to ReST, but a full migration 
implies quite a bit of cleanup after that first step and that can't be a 
one-man show.

1.a) As a side note, about indexed_search: the manual was extracted from 
the Core a long time ago, because it was so large, it might be the 
opportunity to bring it back, but this is a separate (sub)topic IMO.

2) My plan would be to a the absolute minimal cleanup and get the 
migrated manuals up in some repository so that people can start 
contributing. I don't know what's best here, if it should already be 
merged to the main repository at that point or if we should be working 
in a sandbox or a Github clone. I would be glad for advice and opinions.

3) At T3DD13 there will be a day-long workshop about ReST by Martin 
Bless. At every full hour Martin will be available for a short 
introduction. This way many people should be able to attend it, as you 
can pop in pretty much at any time and be sure to receive an 
introduction (not be lost in the middle of on ongoing workshop). We hope 
you will be numerous to attend, as ReST is your future ;-) Improving 
migrated manuals will be a great way to get started with ReST.

4) Following up on this post, I hope to discuss, brainstorm and end up 
with a plan for integration of ReST-based manuals in the TYPO3 BE. 
Indeed a ReST-based manual cannot be viewed offline (at least not 
comfortably) so we have to provide solutions, also taking into account 
that some TYPO3 installations may be disconnected from the Internet. I 
will open a separate thread for this, as this mail is getting too long ;-)

5) At T3DD13 (again) I will organize a workshop with the goal of 
starting the integration/coding of the ideas that we will have come up 
with here. The goal is to have a team that will feel responsible for 
this and continue to work on it in the future. I definitely don't want 
you to think that I will bear this alone, because we might as well not 
do it in such a case.

Feedback on this first post is welcome. I'll open a second one for 
brainstorming about integration later (but still today, probably).

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch