[Typo3-doc] Reason for dropping DocBook...

[Jean-Marie Schweizer]

Hi Bernhard

Nice to see you in here for a change.

> I'm from the programmers side and I must say I don't dislike it so very 
> much to write documentation.
> 
> It helps you to clear things up in your head and get an "written" not 
> "coded" overview over your extension ...
> It also shows you up what will be too complicated for users when it is 
> even hard to understand in the
> documentation ...

That certainly doesn't have to change. I can see that it can help to 
gather your thoughts as you mentioned.

But we have to consider the bigger picture, where it is not anymore 
about one single documentation but about all of them together. We have 
discussed that last summer in great length and agreed that the biggest 
problem with the current documentation is not that it is not documented 
but that is hard to find.

To cope with that problem we need a format that can handle complicated 
structures and numerous levels of depth within a global documentation 
tree. We also need guidelines that help simplify the writing process as 
opposed to the extravaganca along with creative individuality that 
complicates things.

We are talking about several levels of change here. Nothing that can be 
done in a few weeks. But certainly something that can be focused on as 
TYPO3 grows.

With that in mind I rather see specialists, the documenters, the are 
very much like the programmers, knowing the API and following strict 
guidlines to keep the code (the documents) clear.

Of course, any programmer who wants to, can be a documenter.

> But why I write: I would really appreciate going for LaTEX. AFAIK it is 
> used for many years
> in the book-production industry and produces overall good output in pdf 
> and html ...
> 
> I also think programmers like it more, to write plain text and do the 
> markup also via plaintext commandos, than
> to write in a graphical interface with hundreds of buttons and boxes ... 
> (just my humble opinion)

Although I don't see programmers writing documentations as a general 
rule I agree that there is a great benefit in writing in plain text. I 
wrote a few papers in LaTEXT and realized how all the sudden I was 
focusing on my writing rather than the bells and wistles of Word or OO.

> Could you please tell a little bit more about docBook and how one enters 
> text into it. It was already pointed
> out that there's no GUI for docBook ... so do I also have to enter my 
> markup as text ? (i would favor that)

DocBook is pretty much like LaTEX in terms of usage. You have a markup 
language to learn and write it in plain text. The big advantage of 
DocBook: it is XML. It comes with DTDs and Stylesheets, has several 
approved XSLTs and also the FOs for PDF and Postscript.

Anything that would be programmed to implement DocBook into TYPO3 
shouldn't be hard to adapt to other XML based requirements.

> One more question which arises is if it would be possible to convert the 
> already existing documentation to the
> new format as it would take a very long time (years) to convert all the 
> existing documentation manually ...

Sylvain managed to program VIM to convert the typo3.org HTML to Wiki so 
I think it would be possible to do that for XML too.

If we'd take the step to structure all documentations and adapt it to 
new approved guidelines then we would have to go through all the 
documentations. Keep in mind that most of the documentation would need 
an update anyway.

Jean-Marie