[TYPO3-doc] DocBook: sample reference file

[Thomas Schraitle]

Hi Stefan,

Saturday 19 February 2011

> Am 19.02.11 14:05, schrieb Thomas Schraitle:
> > You mix two different target groups with different needs: developers and
> > beginners.
> 
> Yes, I do. But I think it would be totally OK to have one manual for
> beginners AND developers and one for core developers (which have to know
> how TYPO3 internally works).

Well, maybe it depends on how you define "beginners": Are beginners people who 
doesn't know TYPO3? Or do they have a basic understanding about TYPO3, but 
haven't wrote nor developed yet?

If the "beginners" term are better described with the first definition, I 
would't mix them with the developers target group.


> Because I'm working with TYPO3 now since version 3.6. and I still don't
> know what the real difference between cObjects and functions is.

Me too. ;)


> You can
> blame me for that, but I have to say that I'm not embarrassed, cause
> every TYPO3 dev I know personally, doesn't know either. (And I'm not
> talking about TYPO3 newbies). For using an API, I shouldn't have to know
> how it internally works.

I don't blame you. :) In my opinion, it's totally natural _not_ to know 
everything.

 
> If you ask a TYPO3 developer (who has already done 3-4 extensions or
> maybe even 10) what the difference between "data types, functions,
> top-level objects, content objects, and GIFBUILDER and MENU objects" is-
> how good are the chances that you get a satisfying answer?
> I guess not very good, and I think the reason is that it is really
> complicated.
> [...]

Maybe I just didn't grasp your idea, but for me this sounds as a matter of 
good writing style. Nobody understands your text? Revise it! :-)


>  >> I think that we
>  >> have to really hide the complexity, so TYPO3 beginners are not afraid
>  >> of typoscript any more.
> 
> what I meant was, that it is really a huge problem for TYPO3 newbies.
> But it also makes live hard for extension developers/integrators.

Probably your impression is correct. But are your "TYPO3 newbies" the same as 
"TYPO3 beginners"? It seems I'm splitting hairs here, but IMHO the two groups 
has to be clearly definied. I guess, the life that makes it a "huge problem" 
for TYPO3 newbies/beginners are maybe a little bit different than for 
experiences developers.

If this is really the case, address these two groups with two different 
guides. For example, a User Guide or a Quick Start Guide targetting at 
absolute beginners _has_ to be written differently as a Reference or TYPO3 
Developers Guide who know already some details.

Hope I did't confuse nor insult anyone with my perception. :)

Cheers,
  Tom