[TYPO3-doc] ReST Migration: planning the next steps

[François Suter]

Hi all,

As you could see recently, Martin has made huge progress on getting 
ready to migrate the existing OO manuals to ReST. This was our obvious 
first step. Now come the next steps, of which there are quite a few, 
each raising questions. It's a pretty long post, sorry.

To have an overview of what's involved, I tried to list all the elements 
that came to my mind and set them out in a mind map. You can see the 
result here:

http://www.mindomo.com/view?m=c70320665abb48519fda5d67726d633e

(I just tried this service; it's nice, but in Flash; if anyone has a 
recommendation, I'm all ears).

Here are the main points that we need to tackle/discuss:

1) there's very little to decide upon to be ready to migrate all 
existing manuals. Essentially there 2 open questions (you may have more):

a. as far as I can remember, we haven't defined which types of 
admonitions we want to use, since the concept was not so formal in 
OpenOffice. When we were preparing for DocBook migration, we chose 
"tip", "note" and "important". The same levels exist in ReST, so I would 
suggest to stick with this.

b. we need to decide how we want to split the OO files upon migration to 
ReST. We don't want to stick to monolithic files, especially since each 
ReST file (possible within a subfolders structure) will translate into a 
HTML page and hence in a page on the future documentation web site (with 
subfolders translated to a path hierarchy). The current workflow on 
typo3.org splits manuals on Heading 2 titles. I would suggest to go one 
level deeper and split on Heading 3, to make for shorter pages, easier 
to link to. Depending on the manual, we could also go for a finer split. 
In particular for the TSref, it would be great if we managed to have one 
page per object (or even per property?), so that it could act as an easy 
to access reference. This particular case may require manual work.

c. another very important point is the generation of id's. Can we manage 
to automate the generation of id's, at least up to a certain level. 
These id's will be necessary for cross-linking and it would be good if 
we didn't have to create them all manually. This step also implies 
finalizing naming conventions for id's, which we haven't done yet.

2) we need to decide what to do with new manuals. This includes stuff 
from the BLE project (written straight in ReST), but also the upcoming 
new templating tutorial. My opinion is it's a waste of time to write new 
stuff in OpenOffice. We should go straight for ReST and provide a 
temporary structure for accessing this new documentation. I plan to 
request quickly a new server from the server team, which would respond 
to "documentation.typo3.org". This is where we would have the 
documentation eventually anyway. We could host the rendered new 
documentation in a temporary structure, clearing marking it as alpha and 
warning people that all URLs might change in the future.

3) the big next step is the rendering, of course, with the more complex 
stuff like cross-linking. We also need to prepare a HTML template. I 
have suggested using a HTML/CSS framework and Martin has now looked 
deeper into this and agrees to this. I proposed Twitter Bootstrap [1] 
and he came up with Foundation [2]. Does anyone have experience with 
either and could make recommendations? Or yet some other framework?

The other points in the map are less urgent or complicated, at least for 
now, although they will require quite some discussion in the future, 
like how to handle the rendering pipeline/job queue for rendering 
manuals? Although people will just surf the rendered HTML on the 
documentation server, do we want to also have database entries for each 
rendered manual in order to have some way to query the documentation 
database more directly than crawling the site? And other such things, 
but I think this post is already long enough.

Please give your feedback on the above points. Also don't hesitate to 
express your worries or to ask questions if you feel like you're missing 
some information.

Cheers

-- 

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

[1] http://twitter.github.com/bootstrap/
[2] http://foundation.zurb.com/