[TYPO3-doc] documentation format vision (wiki vs OOo)

[Daniel Brüßler]

Hello Jakub,

I'm "thy wiki man", so I answer you for this.

Because of the large number of document-sections (for me that's the
smallest atomic element) we need some automation in this. And the only
problem is to have time to do it. So if you have some time, then tell me.

So I list some tools what are existing or planned
* current: better captcha for direct links pointing to wiki-pages
* existing: bridge from wiki to bugtracker: tag "bug"
* existing: bridge from wiki to TER: tag "extension"
* existing: tagging for all wiki-content with keywords. see "topics"
* next: export from whole wiki-page or partly into OO, DocBook, Creole
(=wiki exchange-format), simple text for putting stuff in newsgroup
* planned: import from any document into the wiki or into a section of a
wiki-page
* planned - support for Robert: optimize rendering-problems of OO and
DocBook for TER
* planned: some bots for the mediawiki, so that text-changes are no problem
* planned: optimized "other resouces" for links in OO-docs and in
wiki-docs so that we get rid of broken links

So you see, you can help if you like. :-)

kind regards
Daniel Brüßler



Jakub Tesinsky schrieb:
> Hello,
> 
> I think that there is some fundamental flaw in the wision of Typo3
> documentation.
> 
> When I have seen typo3 wiki for the first time, I have been
> automatically taking for granted that the commonly shared vision is to
> convert all documentation to wiki and than give it a clear structure so
> it connects well to typo3 backend application. Later on I have found
> that there is no such intention and I think that this is a very wrong
> thing. I am not trying to start flame here, I admire typo3 project and
> the incredible amount of work put into it. And that is the reason why I
> write this. Because I see huge loss of energy of documentation writers
> because of not settled and agreed vision. I thing this should be
> changed. I personally do have a vision, but I am far from saying it is
> the best one. I simply say, that there should be SOME vision in the
> whole effort.
> 
> My vision is: Put every piece of written documentation in a wiki and
> then start merciless refactoring. The reason for that is that status quo
> is:
> * There are loads of well written documents on majority of subjects
> regarding typo3.
> * Generally documents are long and they overlap in details.
> * Usually when you are looking for some information, you find out that
> several documents have useful parts - but there is no interlinking, no
> clear overall structure.
> 
> I think that shows that the documentation currently needs refactoring
> rather than writing new docs. And I think that wiki is right tool to do
> that.
> 
> I could elaborate more on any of my statements, but I hope I have been
> clear enough to show the main idea.
> 
> Keep the good work.
> 
> Jakub