[TYPO3-dev] [TYPO3-english] Bye-bye OpenOffice, welcome ReST

[François Suter]

Hi Philipp,

> End of frustration post

It's normal to be frustrated every now and then. However such posts are 
rarely helpful.

I thought about many ways to answer yours, and I guess most of them 
might have escalated into a flame war. Luckily there's a good way to 
answer: some people here had very good reasons to move to reST.

The people in question are the Documentation Team, which I lead. I'm 
sure you will agree that having good and up to date documentation is as 
important as having good code (if you don't agree, we might have some 
problems getting along ;-) ). Kasper left us a huge legacy. He did a 
formidable work of documenting how TYPO3 worked and what were the many 
configurations syntaxes and options (TCA, TypoScript, TSconfig).

This has to be maintained. It is a huge work. The format really didn't 
help. Most importantly because it's all binary files we couldn't easily 
review someone else's work. To simply update screenshots we had to edit 
the whole manual because the images were embedded (the rendering on 
typo3.org failed with linked images). And sometimes OpenOffice would 
screw the whole document beyond repair.

Thus the Documentation Team decided to switch format. There were lots of 
discussions, but we focused on DocBook, which is a reference in terms of 
writing documentation. And the Flow team had started to use it. Soon 
after that the Flow team discovered reStructured Text, fell in love with 
it and convinced the Doc Team. It wasn't too  late to switch.

Now we have a text-based documentation which means we can patch it and 
reviews each other changes the same way we do for code changes. We can 
update screenshots independently. We can safely cross-link between 
manuals like we never could before. We don't have OpenOffice screwing up 
headers and paragraphs suddenly because the rendering happens 
server-side. I could list yet more advantages.

> why cant you focus on making typo3 less shitty then work on such minor important stuff?

Don't forget that this is open source. Each contributor makes up his own 
mission. There are a few who strongly believe in documentation and they 
make the Documentation Team. For us having an easier to maintain 
documentation is not minor at all. It is critical.

Some manuals are still out of date, but on average the TYPO3 
documentation has never been as up to date as it is now since Kasper 
originally wrote down all the stuff that was in his head. Some of the 
manuals are even now updated as code changes get committed, which means 
you have a "development" version of manuals which match current 
"development" version of the Core.

And we strongly believe that we make TYPO3 less shitty by improving the 
documentation.

I hope this will help you understand the situation better. I also hope 
that you will be more mindful for your next posts.

Cheers

-- 

Francois Suter

Work: Cobweb Development Sarl - http://www.cobweb.ch

TYPO3: Help the project! - http://typo3.org/contribute/

Appreciate my work? Support me -
http://www.monpetitcoin.com/en/francois/support-me/