[TYPO3] Complicated documentation? No reference guide? Do you know any good documentation?

[Dmitry Dulepov [typo3]]

Hi!

Karol Martinka wrote:
> I'm a programmer (mostly C++ & Delphi), I do understand object-oriented 
> concepts, but Typoscript was harder to understand from the doc's as 
> Smalltalk is ;-)..

One thing that you must know is that TS is not a programming but a configuration language. It is not executed, it ~describes~ how objects look like.

> Let me say some comments :

<skip>

> IMHO it would be better to provide one FINAL code example and explain 
> row-by-row, what you can do with this and that property, object etc... And 
> also, there is a missing "object description" . - What is a "page" ??? 
> Everybody knows, but why you have to initialize page=PAGE? what is typeNum ? 
> what else can page contain? which properties? what does it mean if you write 
> "temp.mainTemplate" ? should it be temp.mainTemplate or can it be 
> something.someThing ? Lot of unanswered questions - BUT there are simple 
> things described - like "check the file extension to find out the file type" 
> :-D . I don't think that a Typo3 beginner does not know, what is a file type 
> and extension but I'm sure he definitely will not know what does it mean 
> temp.mainTemplate..

Well, yes, this is a good example of what is difficult for beginner. This is exactly the problem I am talking about: developers assume things as known by anyone, while beginners do not know it. It is like saying to three-year old child (no offense!): "Read that book about solving puzzles" without realizing that child should be first tought how to read!

> And about the reference - let me explain it on an easy thing - 5.8. typolink 
> :
> 
> O.k. it wraps the incoming value with link.. Hey-stop! what does it actually 
> mean?? typolink is a important function but no explanation at all.
> Why there isn't a short sample on the beginning, how it should look like in 
> the typoscript? Or for example the "additionalParams" property - there is a 
> sample '&print=1' . Why this sample is not written like 
> typolink.additionalParams = &print=1 ?  It's a little more of text, but 
> everybody can read it. If you write '&print=1' a beginner will not know on 
> the first sight if it is a sample of URL string in the browser and he has to 
> read more about figuring out, how to do that, or if it is the VALUE of the 
> property of the typolink OBJECT..

For the typolink: it should be emphasized that people should start reading TSRef from top level objects (TLOs) like PAGE or CONTENT. Then they will see "typolink" and can refer to corresponding section. But I got the point. There is something to think about. May be at least to rearrange sections.

-- 
Dmitry Dulepov
TYPO3 core team
Web: http://typo3bloke.net/
Skype: callto:liels_bugs
"Nothing is impossible. There are only limits to our knowledge"