[TYPO3-doc] Do you miss a HAT

[Tim Wentzlau]

Hi List,

I have followed the discussion on the general list regarding the 
sometime poor quality of the documentation of the T3 system.

All the complains about the documentation proves to me that T3 and the 
T3 community needs a HAT (Help Authoring Tool) to overcome the troubles. 
T3 is not the first project that has come into these trouble when it 
comes to documentation, it happens all the time as projects grow. There 
exists a lot of commercial HATS that are very (I mean VERY) expensive. I 
have used AuthorIT for several years and I really missed all its 
functionality when I last week wrote my first extension manual.

These days a good HAT include the following elements:

1) Single source
Write the documentation once and publish into various formats, HTML PDF 
help files and so on.

2) Modularity
Most systems are build from subsystems to avoid rewriting the same text 
in different subsystem a good HAT should be able to combine the 
documentation for subsystem into bigger systems.

3) Version management
As a system evolves it should be possible to maintain the documentation 
for several versions.

4) Multi user support
Working on large system often requires many people that works together 
in the documentation process. This goes from the programmer that writes 
to initial documentation to help desk supporters and Tutors that updates 
the documentation based on experiences in the wild.

5) Workflow and approvals
To avoid wrong text, typoes and general misunderstandings in the 
documentation process.

6) Support for localized documentation
In this globalised world all documentation needs to be translated into 
several languages.


Does all this sound familiar to you?
What system in the open source community could offer that?
(silence)

TYPO 3 !!!!!!!!

With version 4 of Typo3 we have in our hands a powerful HAT and it comes 
almost natively.  The entire editing process and generation of HTML 
based documentation is covered of the box. Left is publishing to PDF.

My proposal is that we should make a T3 documentation server with of 
course T3.

Instead of writing Open office documents and then convert them into HTML 
we should write the documentation directly on the T3 documentation 
server. If we do that we would take a giant leap when it come to the 
quality of the documentation, availability, translations ect.

If we set up a T3 documentation server with Templavoila and 
Multilanguage support we have all that is needed. The current T3 
documentation team could be administrators and all extension developers 
could get a sub tree for each extension. This could be done 
automatically when a extension key is registered.

For each extension there could be a comment system or discussion forum 
and why not FAQ system. (they come all out of the box)

  Do you know what I am saying :-)

Tim