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

[Jean-Marie Schweizer]

>>What was the reason for dropping that idea?
> 
> I'm not sure if I can give the full answer, but I know that one of the
> reasons is that there simply doesn't exist any useful frontend to
> docbook.

I see, it is similar to Wiki where there is no real frontend either, 
since you simply edit a textbox.

> Robert and I had a look at some diff apps this fall, none of them
> we're good. Most programmers already hate writing docs, forcing them
> to use something with a steep learning curve isn't really a good idea,
> unless there are some really good reasons to.

I agree that putting a learning curve on the programmers would be a 
waste of resources. But asking documenters to learn a certain syntax 
(and I believe that the learning curve of DocBook is not that high for 
what we need it for) shouldn't be asked for too much.

I realize that it cannot replace a Wiki as far as ease of writing 
content and get users to spontaniously write a few lines but I also come 
to the conclusion that if we want a professional documentation for TYPO3 
neither the current typo3.org with SXW nor the Wiki can be it.

If we look closer where we are headed with TYPO3 everything points to 
cleaner structures. As much as programming profits from a neat code so 
does documenting.

A few pointers to explain a little more:

1. A programmer should be able to reduce his documenting efforts to 
documenting his code.
2. Programmers should work hand in hand with documenters so that the 
documenters can take over the writing process as close to the code as 
possible.
3. One way to accomplish this could be (Robert may remember this 
discussion from last fall) that the programmer simply records a video 
showing his extension (very much like the CD collection by Kasper)
4. A documenter writes the documentation according to the docTeam 
guidlines from the video.

This szenario would mean that the programmer should be able to spend 
more of his valuable time concentrating on programming and testing 
rather than documenting. And with trained documenters we would be able 
to follow guidlines and write the documentation in a format that doesn't 
present us with obstacles as soon as we need it to be structure overall.

This makes clear that we are talking about at least two classes of 
documenters:

1. The ones that just want to help out and write a few lines about a 
problem or so

2. The ones that want to contribute to TYPO3 in the long run.

For 1 we have the Wiki, quick and easy, nothing complicated. It's more 
about getting something done quick than right. So, it's not going to be 
possible to ask those people to follow guidlines because we are happy 
that they contribute.

For 2 we need a professional documentation solution (DocBook, LaTEX 
etc.) that allows us to structure, work in teams, follow guidlines and 
have everything in a format that can be converted in whatever we need. 
So far I only know of LaTEX and DocBook who can do that where DocBook 
follows the XML syntax.

Well, I close here for now and see what you guys mean.

Jean-Marie