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

[Daniel Siepmann]

On 2012-03-08 16:05:09 +0000, François Suter said:

> 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):
> 
> 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.

Just my personal opinion, I dislike the small pages like blog articles 
where you have to click 1, 2, 3, 4, 5, 6 for just one article. I like 
one page per information.
So one page for each TypoScript object sounds good. One per property 
will let you click to many links for the information you need. And most 
people are just using the online documentation, they will not be able 
to print one object without printing multiple Websites.

> 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.

+1 Like said before, short urls are nice. So make docs.typo3.org the 
new official home of all documentations. Just one resource where you 
can link to forge, wiki, blogs, articles, snippets with more 
information. But keep all together at one point. It's hard to get all 
information for one topic at the moment.
And of course, warn people about changing urls.

> 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?

I worked a little bit with Twitter Bootstrap and it's really nice for 
me as a programmer. I'm not familiar with styling and Bootstrap makes 
it very easy. There are some nice JS-Plugins. All you have to do is to 
use the markup. I can't say anything about Foundation.

I'm really looking forward to this big changes. The best new feature 
will be the cross linking.

--
Best Regards,
Daniel Siepmann.