[TYPO3-doc] Do you miss a HAT

[Tim Wentzlau]

Hi Matthew,

I tried to send this reply yesterday but it seems as there are trouble 
with the news server.

 > As I see it, changes to existing documentation is steady ongoing 
process and
 > largely each document is the work of one main author as titled in the
 > document itself.
 >
 > So changes can be sent straight to the author to review and release.

That is true for now, but Kasper and the core team are busy creating new 
teams that should take responsibility in a broader way in the T3 
community. Based on my experience from other projects I know that this 
will require collaboration tools to handle effectively and especially 
documentation is a place where there collaboration tools are required.

 > I think the main reason for the earlier discussion was simply a 
combination
 > of:
 >
 > 1) People did not know other lists existed
 > 2) They did not find the existing documentation they needed
 > 3) typo3.org is still hard to use to find the documentation/answers you
 > need.
 > 4) Probably the people do not know TYPO3 idiosyncracies enough to 
find/ask
 > effectively.
 >
 > Again the discussion arises, how to help new people find enough 
information
 > to help them learn TYPO3 enough.

This question has been asked several time in other software projects and 
the answer to this question is to construct and organize the 
documentation properly. In a multiuser and multi language system at the 
scale of T3 only a HAT system will offer the needed foundation for this 
succeed.

 >
 > It seems that many people learning TYPO3 are not willing/able to 
learn typo3
 > from the structure and need TS snippets to help them achieve the function
 > they need.
 >  They have pressures of time and work.

 > Generally TYPO3 understands that hence the excellent document TS by
 > Example.

I am a developer with a master degree in science from DTU in Denmark and 
i did found it very difficult to comprehend the basic ideas behind T3 
tree years ago when i started with T3. But when you get hold on T3 you 
come to love its flexibility and extensibility. But the start was rough 
and after coming thru i think (i know) that it could be done smarter.

 > But there comes a point where a person needs to go beyond that and learn
 > TYPO3. This means an investment of time reading the great reference
 > documentation.
 >
 > So again the discussion on new people learning. What can be done to ease
 > their learning. Possibly a more structured lesson/documentation outline?
 >

You give the answer your self good structure in the documentation is 
paramount. With a good HAT you we will be able to construct 
documentation on different levels with lesser effort than to day. If 
setup correctly it could generate several books on the fly in several 
languages.

Another topic is how to write the manuals. I dont think that the process 
that is used today where Open Office files are converted to DocBook 
format is the best way. Open Office files a monoliths that are difficult 
to handle and organize an the conversion to DocBook format implies that 
only very specific formatting is allowed.

This degenerates the quality of the produced manuals as it is not 
possible to make a manual that takes into account the knowledge about 
people learns.

The only way out for T3 is HAT system and we could turn T3 into a very 
good HAT.

Tim