[Typo3-doc] Wiki people: who's on board now?

[Robert Lemke]

Hi Alex,

Alex Heizer wrote:

> Thanks, Robert. In regards to the technical parts, and the rest, I
> contacted Ton Roosendaal of the Blender Foundation yesterday and got a
> very quick reply! They are using T3 for most of their site, except for
> some legacy sections, and he said: "BTW; I've only heard good stories
> about the typo3 documentation :)   Probably your choice for open office
> was a good one!"

I think it was Ton who I met on on a PHP conference in Amsterdam - they
really like TYPO3 ;-)

> Evidently the Blender Foundation had some problems with the DocBook
> format, which he attributed to the collaborative nature of their doc
> team. However, he pointed out that it has been used successfully by
> others, so how we use it may or may not determine whether we encounter
> the same problems. To wit:
> 
> "We had big difficulties with DocBook. Not only is the format design
> very clumsy and not user friendly (there seems to be still no good
> WYSIWYG editor for it), exporting it only has caused troubles...
> especially when the books are large (bug in pdf exporting forced us to
> do it in parts) and exporting for DTP design of real books failed too
> (no support for Adobe Indesign for example)."

I agree that writing DocBook documents without any help by a nice editor is
something you have to get used to. But I'm confident that we find a nice
way - the first and easiest option is to define certain styles in an Open
Office template and convert these documents to DocBook and the second and
more fancy option is to create a frontend plugin which allows for DocBook
editing.

> They have found a wiki to be their best tool for collaborative writing,
> but then we had already agreed here that having a wiki-like interface
> for editing was something we wanted in our system. Fortunately, I think
> we may have some programmers hanging around who can give us a system
> with a wiki-like editing interface that saves to a standard document
> format that can be used and exported in other ways!  Hint, hint! :-)
> What are the technical limitations/benefits of the DocBook format that
> we may encounter? And how soluble are these limitations in regards to
> the software system we're considering?

Okay, let's assume that it's no problem technically - we have a wiki-like
editor which converts to DocBook. The main reason why you want to use
DocBook is that it adds much more semantics to your document than, for
example, an OpenOffice Writer document.

When you select "Courier 10pt red" in OpenOffice, a parser can only guess
that this is a code snippet. We can assume that the first paragraph in the
document is a copyright notice or that headings of level 1 are chapter
titles.

In DocBook you have this information:

<code language="TypoScript">
     10 = PAGE
</code>

Meta information about a document:

<bookinfo>
  <title>TemplaVoila</title>
  <authorgroup>
    <author><firstname>Robert</firstname><surname>Lemke</surname></author>
    <author><firstname>Kasper</firstname><surname>Skårhøj</surname>
      <affiliation><orgname>TYPO3 Association</orgname></affiliation>
    </author>
  </authorgroup>
  <edition>Manual for version 0.4.0</edition>
  <pubdate>2005</pubdate>
  <copyright><year>2003</year>
    <year>2004</year>
    <year>2005</year>
    <holder>Kasper Skpårhøj</holder>
    <holder>Robert Lemke</holder>
   </copyright>
</bookinfo>

A very useful feature are callouts [1] which allows you to put some marks
into a screenshot or code listing which associate with annotations.

DocBook is quite useful when it comes to translation. Because screenshots
are marked as screenshots and the document has a proper structure, it's
easier (or possible at all) to integrate the documents into a translation
framework.

Generally, exporting DocBook is no problem - really. As soon as we have
proper DocBook documents we can easily produce PDF A4 / Letter, XHTML for
download, Windows Help Files, Open Office, RTF, ...

So, back to the wiki question: Even if we had such an editor, we still have
to add some meta information. The question therefore is if we really want
to take advantage of the DocBook format and have all the meta information
or just misuse it and work with wiki style editing. 

I'd like to ask you having a close look at the KDE internationalization site
[2]. They seem to use DocBook quite successfully and have good
documentation how to use it.

> Hey, any avenues we can exploit (oops, I mean *explore*!! ;) ) to get
> volunteers is a good thing! We have a couple of good writers on the US
> team. I think we still need to have reviewers who can go over all the
> existing information and organize what is there in terms of
> appropriateness for placement in the document structure. And, of course,
> technical people who can work on the system itself. I think things are
> moving very quickly in the group (good), and some of us are impatient
> (me), and momentum is easy to lose (bad), but there is a lot to do
> (good) and we have time on our side (good).

By the way: One task which has been open for two years now is the "Start
here!" page in the documentation section [3]. 

I have chosen another structure for the new TER [4]. Please have a look at
it - what would you like to change? We should create proper texts for the
documentation section during the next three weeks so we can use them when
the TER2 goes online.

Cheers!
robert

[1] http://www.docbook.org/tdg/en/html/callout.html
[2] http://i18n.kde.org/
[3] http://typo3.org/doc.0.html?&tx_extrepmgm_pi
[show]=startHere&cHash=a3b7f4ccc2
[4] http://ter.dev.robertlemke.de/documentation/
-- 
Robert Lemke
TYPO3 Association - Research & Development
Member of the board
http://association.typo3.org