[TYPO3-doc] Deeper changes to the documentation

[François Suter]

Hi all,

I alluded to deeper changes in the thread about "small improvements to 
the official documentation template" (which has turned out to be about 
"very large changes" ;-) ). Here's more information about what is mostly 
reflections for now (no real decision, no formal action taken yet).

NOTE: I'm going to just use "documentation" for the remainder of this 
mail, but I really mean "official documentation".

It actually all started during T3DD10 when Robert Lemke came to me and 
said that we should take care about making the v4 and v5 documentation 
converge. I was thinking about the same. However it's only recently that 
we finally had time to have a conference call on the topic.

As you know v4 uses OpenOffice and v5 uses DocBook. Moving v4 
documentation to DocBook has been in the air for a long time, but never 
got anywhere. When I picked up the official documentation again, my main 
worry was to refresh it and not change any of the technical aspects. I 
didn't have enough time to manage all the impacts a technical change 
could have (on typo3.org, on TER, on EM, etc.).

The topic is still actual. When discussing with Robert we listed a 
number of pros and cons. We are not done yet, because this list of pros 
and cons raised some questions for which we want answers first. As I 
said before, no decisions whatsoever have been taken yet, but DocBook is 
still in the air.

The other point we came to was that we needed a professional design for 
our documentation template. The current designs for both v4 and v5 
documentation were not satisfying (although the v4 design has evolved a 
lot recently). I'm currently in touch with someone who could help us 
doing this redesign and who - incidentally - also knows a lot about 
DocBook and its conversions.

In this light, some of you might wonder whether the efforts we are 
currently putting into refreshing the v4 documentation template are 
really worth it. IMO they are, because the current work is helping us 
define far more clearly than before the structure of our manuals. This 
inventory will be necessary when creating a new design. Furthermore this 
whole project could take quite some time and it's good that we already 
deliver an improved template in the meantime.

More information will follow in the near future, but probably only after 
T3CON10, because preparing for the conference keeps me pretty busy for now.

Cheers

-- 

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