[TYPO3-doc] DocBook: sample reference file

[Thomas Schraitle]

Hi Stefan,

Saturday 19 February 2011
> 
> I have to disagree here- personally I don't think that this structure is
> important for TYPO3 extension developers/integrators. (Maybe we need to
> discuss some use cases / target group for the manual).

That's exactly what I miss here.


> I think that we
> have to really hide the complexity, so TYPO3 beginners are not afraid of
> typoscript any more.

You mix two different target groups with different needs: developers and 
beginners.

For developers an exhaustive/extensive reference might be what they exactly 
need. A developer searches for a function, its arguments, and probably want to 
know some examples how to use it. They know the concepts already.

In contrast, a beginner (like me ;) searches exactly for these _concepts_: 
what's the syntax, how can you call your script, do I have to observe some 
naming conventions, what's the "best practice" etc. All the gory details.
Sure I would be probably lost by an exhaustive reference of functions, 
objects, etc. But that's not what I'm looking for -- at least in the 
beginning. :)

As such, it's better to separate these target groups clearly and give them 
what they need. Developers get their reference guide and beginners get their 
quick start guide. If you want a beginner "not being afraid of typoscript" 
just make the quick start really good instead of trying to "hide the 
complexity" in the reference guide.

In my humble opinion you are barking under the wrong tree. ;-))


> [...]


Cheers,
  Tom