[TYPO3-team-core-v5] TYPO3 Phoenix Scrum Meeting Notes - 21.07.2011

[François Suter]

Hi Robert,

> yes, I know – and that's also why I as very reluctant to check out
> alternatives. On the other hand there was this apparent feeling most
> in the time had for some time now that writing and handling DocBook
> might be too heavy.
> [snip]
>
> I'll get back to you as soon as I have more insights!

Well, make your tests then, but please consider this very seriously. The 
efforts that we (the Doc Team) have already invested are far from 
negligible and I think quite a bit would lost, contrary to what you 
think (very little design work has been done yet, which is what would be 
mostly salvageable).

Please mind the pros and cons listed for DocBook:

http://wiki.typo3.org/DocTeam/DocBook_migration#Pros_and_cons

when you evaluate ReST. To this list I would actually add the ease of 
cross-linking (when using DocBook id's), which is a major issue (we have 
tons of broken links in the current documentation).

I know that DocBook is not so easy to write for contributors and this 
was hotly debated in the documentation mailing list. We finally came to 
the conclusion that the added complexity was worth it compared to 
DocBook's feature set. We also figured that only few people are 
contributing to the documentation anyway and that they will probably be 
okay learning DocBook.

I would like to add that this is not just about me. It's also about the 
Doc Team and its role. We have been building it up, making it more 
active, more professional and I'm disappointed that discussions about 
the choice of a documentation format should happen among v5 team members 
with no coordination with the Doc Team.

Cheers

-- 

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