[TYPO3-doc] Do you miss a HAT

[Tim Wentzlau]

Peter Kindström wrote:


> If we want to do this properly, we have to deal with ALL aspects of 
> documentation, not only get people to write. We already have a lot of 
> documentation and people still think it is hard to find information...
>
I agree that we need to look at the entire process but i think that 
Edwin meant that we would come a long way by offering good structured 
documentation in an on-line version made by T3. The next step could be 
to create different kind of off-line documentation. And i agree with 
Edwin if this is the case.

It is difficult to find the documentation, I have been using T3 for 
about 3 years and I still come across a piece of information that I 
didn't expect to find at that spot.

> No, producing documentation is not the biggest problem (yet). Right now 
> we need to organise both the content, the documents, the presentation of 
> them and the document management. When that is done, we can speed up 
> production again!

One of the great things when it comes to T3 is that there is a 
documentation culture that is something that many other open source 
project miss. What we miss is the HAT the HAT is to documentation what 
CVS is to handling source code. Could you imagine handling a project of 
the size of T3 without proper source code management.


> 
> I know this sounds boring to some of you, but then you don´t have to 
> participate! I believe that organising is the key word here, and a HAT 
> system is a part of that. The other part is structure.
 > It doesn´t matter how good HAT system we have, if people cant find the
 > documents. And it doesn´t matter how easy it is to find documents if
 > they are not up to date!

Use the HAT to make the structure. With the right HAT system you are 
able to organize the same information to be presented on many levels 
from beginners to advanced users and updates will be reflected right 
away thruout the entire documentation.

> ----------
> 
> The biggest problem with the last documentation effort (I was a part of 
> it) was that we had little or no discussions with "the big guys". If we 
> in the DocTeam could not agree, there was no one to take a decision so 
> we could move on. So we did not get trought the disussion phase. :-(
> 
> But I think this have changed lately. Kaspers efforts around Typo3 4.5 
> sounds promising, so mayby it is time to "restart" the DocTeam?
> 
> 
> BTW, the wiki was intended to be *a workplace* for documentation, 
> nothing else.
> 

When lacking a HAT wiki is good alternative but T3 and the comunity is 
at such a scale now that we have to take documentation to anoter level.

With all the plans about teams the time of monolith swx files are over.

I will happily join the docTeam to help with this task.




BUT there is one think that is very important and that is good 
usability, this reduces the amount of documentation needed. Please keep 
this in mind if is hard to describe and make the documentation for a 
certain functionality then it is also hard to grasp for the end user and 
the user interface should be changed.

That is also why it is good to more that the programmer to make 
documentation as other can spot bad user interface alone on the hard to 
produce documentation. In this working process a HAT becomes very handy 
in the collaboration process.

Tim