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

[Daniel Brüßler]

Hi Jakub,

everybody has three roles
* a) use documentation for something you want to be done
* b) extend/ create new documentation/ translate documentation
* c) rate or review documentation

A wiki -- as a tool -- is very good in b), very bad in c and it's OK in a)

Browsing and searching through XHTML-rendered docs are optimal for a)
and combined with the reviewing-extension on typo3.org c) is optimal, too.

OO-docs are very good, when docs must be "one piece", versioned and
delivered with an extension.

U understand?

kind regards
Daniel Brüßler



Jakub Tesinsky schrieb:
> Hello Daniel,
> 
> thank you for your kind respond. Hopefully you can clarify some of the
> things I do not understand. For example there is this point:
> 
>> * next: export from whole wiki-page or partly into OO, DocBook, Creole
>> (=wiki exchange-format), simple text for putting stuff in newsgroup
> 
> Why do we need to export wiki to OO at all? I think that it is important
> to ask this BEFORE one starts to write such tools. What is the role of
> the wiki in the whole documentation project? What is the role of OO
> documents? What is it and more importantly: what we want it to be in the
> future?
> 
> I am not against helping in some way, but I would like to really see WHY
> some things are done first. It is surely possible that I did not
> understand the typo3 movement correctly and there are good reasons to do
> what is currently beeing done. In fact it qould not suprise me at all if
>  I simply overlooked something. But from all I know it seems to me right
> now, that there is not clear vision about the development of
> documentation now. And again: I do not mean it to upset anyone, it is
> just observation and if there is a nonzero probability that i am right,
> than it's better to talk about it.
> 
> Jakub
> 
> 
>> 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
>>
>>
>>