[TYPO3] documentation in general

[Martin Kindler]

I can completely understand you and support your pledge for better T3
documentation although I have a degree in computer science.

First, I admit that the T3 community has given us a wonderful and powerful
tool. And I understand that developers tend to hate writing documentation
(it is all in the (open) code anyway ;-))

There are a few points I want especially to mention:
1. a "mid-level" documentation is missing. There are wonderful tutorials
even as video which show how to do the first steps, just click here, click
there. And then there is thorough referential material. But that can only be
understood if the reader has a thorough mental model of how T3 is working. I
do only know the hard way: read the code and try! This is surely a way to
become rich for a talented book author :-)) I volunteer as a proof reader.

2. documentation is not really up-to-date. I remember a link to a promising
pdf-document in one of the introductory papers everyone is invited to read
first which simply does not exist. And this reference has been there for
several (3+) years. This is just one point.

3. the extensions are not really in a thorough state. Many even of the
widely used ones are in alpha or beta stage. As a newbie you cannot rely on
status information. Then the repository lacks some quality criteria.
Everyone can just upload his latest hack, give no or unusable docs and never
ever update it. It will be in the repository along with the thorough work
horses. Please, do not misinterpret me, open source lives from volunteers
donating their work to the community and I do not want to introduce too much
bueraucracy into the process, but some additional criteria might be useful,
e.g. user ratings for each extension, perhaps a set of formal criteria like
"has documentation", "has been supported for at least 1 year/6 months" or
so. This could give a group of "reliable extensions". The others can be in
some form of "incubator". Otherwise each programmer who needs some special
functionality for a special project writes an extension, uploads it, and
forgets it (until his customer complains).

4. an "extension writing tutorial" is extremely needed. I find myself all
the time writing (small) extensions, but there is no real tutorial which
deals with more than the very first steps. So the learning curve was much
higher.

5. if documentation is not on the highest professional level, than the
community tools (web site(s), wiki(s), mailing lists, archives) should be.
But since the wonderful upgrade of the web site they are incomplete, hard to
use. The "old" mailing list archive (T3 english) has been removed for
performance reasons (I admit there <strong>were</strong> performance
problems. But over 6 months later there is still no real solution. Seems a
bit like techie handling: if I have a problem, stop it (but don't care about
users relying on the functionality). The feedback on the mailing lists is
usually wonderful, but the accessibilty lacks.

If you are a volunteer supporting this great project, please do not read
this as saying you are doing a bad job. I really appreciate your work. But
even a good project can be made better!

Martin

> -----Ursprüngliche Nachricht-----
> Von: typo3-english-bounces at lists.netfielders.de 
> [mailto:typo3-english-bounces at lists.netfielders.de] Im 
> Auftrag von dave ashton
> Gesendet: Freitag, 30. Juni 2006 23:29
> An: 'TYPO3 English'
> Betreff: [TYPO3] documentation in general
> 
> 
> My rant and rave.!
> 
>  
> 
> Basically, I've been putting in 14 hour days for the last 
> month to get a site up and running with all the functionality 
> the client wants.
> 
> Why 14 hour days? Mainly due to my lack of understanding on 
> the typoscript front.
> 
>  
> 
> If its not the extensions that I can't configure, its getting 
> css or javascript elements to work with typoscript.
> 
>  
> 
> Now i know I am slow on the uptake when it comes to 
> programming in general (I'm a designer firstly), but I think 
> I have read tsref, typoscript examples on the typo site, etc. 
> and it is still an uphill battle, feeling at times, impossible.
> 
>  
> 
> As someone who wanted a cms for ease of use and ease of 
> creating functionality in a self contained admin., typo is 
> great, just a shock to have to learn what is like another 
> language on top of the other web technologies, especially for 
> what is a piece of software. (like having to learn VB to 
> write word documents.)
> 
>  
> 
> Now, I'm not saying, typoscript is bad or get rid of it (I 
> know the responses, 'read the docs!', 'do the examples!', 'if 
> you wanted something simple, use another cms!'), but it seems 
> to me, simpler, more complete documentation is needed in this 
> area, almost something like 'typo3 for dummies!'
> 
>  
> 
> Translations of most of the docs. From German to English 
> could be some of it, people documenting for free, also, but 
> nothing is more frustrating than going down a path with some 
> technology, only to find, documentation is poor and I feel 
> bitty and not explained fully.
> 
> I think this is a symptom in general from programming 
> documentation and tutorials. When you understand something 
> well, you tend to miss out in the explanation aspects you 
> take for granted or find very simple, where others or people 
> with less understanding, have no clue about. This I find with 
> a lot for teach yourself books.
> 
>  
> 
> It also seems 99.9% of all postings on the mailing list are 
> from lack of understanding of typoscript and how it works.
> 
> All these people cannot be thick or stupid. But the mailing 
> list is like a programmers forum now, asking for snippets of 
> code. Almost like, ' how will this class work in that class, etc.')
> 
>  
> 
> I feel more simpler information is needed and if a plugin is 
> publicly available it should be documented and only available 
> if stable.
> 
>  
> 
> Is it just me finding typoscript is worse than learning a new 
> programming language?
> 
>  
> 
> Do others feel the same or I am being thick and it is my lack 
> of being able to learn technical information? (which I know 
> is the case in some areas!)
> 
>  
> 
> Dave
> 
> _______________________________________________
> TYPO3-english mailing list
> TYPO3-english at lists.netfielders.de
> http://lists.netfielders.de/cgi-bin/mailman/listinfo/typo3-english
>