[TYPO3] documentation in general

[Martin Kindler]

Dave,

I do not think that charging some money would be a solution although I agree
that 
I would rather pay for a piece of good, well-documented software than get
the bad, undocumented.
But Typo3 is a good piece of software with a lot of dedicated supporters. If
money would be the problem,
the gurus could write another book, sell it and become either rich or donate
some of the price to the project.

I think it is a problem of project organization. If I look at the Apache
Jakarta projects they seem to make 
a better job in providing the necessary environment of docs etc (although
Apache docs tend to be a bit too deep in a technical sense).

The T3 project should set up a set of guidelines and a group of people
enforcing them. If an update to a "core" component (real core or important
extension) is released, there must be appropriate documentation for it,
which has been proof read by other people as the author (I volunteer).
Otherwise it will not be available thru typo3.org.

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
>