[TYPO3] documentation in general

[Martin Kindler]

Just a little mantra each newbie (and many of the old followers) of T3
should say to himself each morning and evening (lunch time is also
recommended):

Typoscript is NOT a programming language. I CANNOT write algorithms in it.
It is a SPECIFICATION LANGUAGE!

I have seen so many postings to this list which show that their authors
compared Typoscript to PHP or Java, C, ... and didn't recognize the
difference. I say this little mantra each day (nearly ;-)) to keep my mind
clear.

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: Montag, 3. Juli 2006 12:25
> An: 'TYPO3 English'
> Betreff: Re: [TYPO3] documentation in general
> 
> 
> Hi,
> From originally starting off this rant, I think a good 
> solution would be for the typo3 software to be like 
> shareware. Pay a nominal amount, say $30 dollars per install. 
> That way, more funds would be available for the typo3 core 
> team and extension developers to write understandable, 
> multi-lingual documentation and to iron out bugs in 
> extensions, etc. Extension documentation should be given a 
> test in itself along with an extension before, being publicly 
> available. Give the documentation to a basic programmer like 
> myself to install and configure the extension. From there, we 
> can provide an easy to follow process of install, 
> configuration and document what files do what, with examples 
> and tons of typoscript configurations, with comments of what 
> pieces of typoscript does what. The docs. can then be given 
> to translators.
> 
> All this costs time and money. So, shareware or a signup 
> system where you pay a nominal amount for each typo3 download 
> is the best way I can think of.
> 
> 
> I think for software as powerful and useful as typo3 I think 
> this is the next step in Open source software. When open 
> source software becomes as complex as typo3, the open source 
> community can only provide free, so much, (they have mouths 
> to feed I expect!)and can only give so much time free. (this 
> may impact on open source licensing, etc. but I don't know 
> anything about that area.)
> 
> 
> I, personally, would rather pay a nominal amount per website 
> and know all the documentation is there for me to just learn, 
> rather than free software, that would cost me more in time 
> hunting out docs. and help than it would to buy an off the 
> shelf product and learn through the documentation they had.
> 
> I know, even commercial software documentation can look like 
> it has been written by either a 5 year old or a computer 
> scientist with no idea about communication skills, but from 
> my experience, commercial software documentation is usually, 
> well, better documented.
> 
> I think as developers, we want to get the job done in a set 
> amount of time and in budget and be confident the software 
> can do the job. Typoscript and some extensions, IMHO, can 
> grind this process to a halt. If a part of a system has such 
> a steep learning curve, it needs documenting to the n'th 
> degree, otherwise, only the most dedicated or daft will keep 
> using the thing. Also, other web technologies are 
> transferable - PHP, css, html, xml. Typoscript is not, only 
> usable in typo3(I think!?!). So, the costs of learning 
> typoscript are even greater.
> 
> I saw a post by a java developer who was looking for a cms. 
> He quoted that due to typoscripts convoluted nature, it would 
> be easier to learn java than typoscript!!
> 
> This is just one persons opinion, obviously, but as a basic 
> programmer, I found this shocking.
> 
> I am not writing all this to put people off typo3 or to put 
> down all the hard work by typo3 developers everywhere, just 
> to outline, that docs. and extensions docs. need seriously 
> reviewing, if typo3 is to be shown as one the best CMS's out 
> there in the future.
> 
> Would anyone start learning a class based language if they 
> knew only basic or not complete documentation was available????
> 
> 
> 
> Thoughts, anyone?
> 
> Dave
> 
> 
> -----Original Message-----
> From: Andrea Giorgini [mailto:a.giorgini at norvlit.de] 
> Sent: 03 July 2006 10:34
> To: typo3-english at lists.netfielders.de
> Subject: Re: [TYPO3] documentation in general
> 
> Martin Kindler wrote:
> > I can completely understand you and support your pledge for 
> better T3 
> > documentation although I have a degree in computer science.
> > 
> 
> Hi,
> 
> as well as Martin I also have a degree in computer science, 
> and I am a 
> PHP developer for about 6 years. Ok, many things for me are 
> clear now, 
> and I have to say that for people like me often is just a question of 
> studying. But Martin is right (IMHO) with his analysis, documentation 
> often is not that up to date and often poor. I also have to 
> say that for 
> the (in my opinion ONLY) alternative - eZ - the point is the 
> same: the 
> learning curve is quite high. I honestly think this is the 
> price to pay 
> to have such a powerful tool, but without any doubt people 
> could work a 
> little bit more on documentation (and this is valid also for 
> myself, as 
> a developer I know we often miss the will to write it).
> 
> My greatest appreciation anyway to the whole Typo3 staff, you 
> are doing 
> a great work.
> 
> Andrea
> _______________________________________________
> TYPO3-english mailing list
> TYPO3-english at lists.netfielders.de
> http://lists.netfielders.de/cgi-bin/mailman/listinfo/typo3-english
> 
> 
> _______________________________________________
> TYPO3-english mailing list
> TYPO3-english at lists.netfielders.de
> http://lists.netfielders.de/cgi-bin/mailman/listinfo/typo3-english
>