[TYPO3] documentation in general

Mon Jul 3 12:46:08 CEST 2006

Hi,

I think that is an excellent suggestion, i would pay $30 dollars with no
hesitation! It has cost my employer 6 months wages to learn and document the
system.

Typo3 does run the risk of becoming so complex, that no new users will take
it up, and only the (as you mentioned) dedicated or daft will remian

Typoscript isnt too much of a problem, you can get by with knowing very
little, especially with the constants editor and tmepla voila. I have put
together a course for an isp, and it only touches on Typoscript.

They dont need to know about it for their needs, so i havent covered it in
detail. but it is confusing,

I agree with the developers comments you mentioned. I can program in many
many languages, and It has taken me months to learn typo3, it takes me alot
less to learn a whole programming language,

Playing devils advocate here, but if the documentation does get too bad,
then people will simply not use it anymore.that would be a great shame, as
it is a great system. If i knew the extent of what i was having to learn, i
would have gone for a different system

I think that this needs to be enforced at the extension repository level. Ok
no one likes doing documentation, but its an integral part of a system.

Some documentation also is aimed at the developer, rather thn the end user.
If someone wants to use an extension, then simply show them, rather than
gonig into major detail on typoscript configurations. Sure this should also
be available, but seperately. I was quite bamboozled by some of the docs,
when all i wanted to do was something really simple

But of course, we wouldnt even be able to rant if it wasnt for the great
work the developers do ;-)

jamie

-----Original Message-----
From: typo3-english-bounces at lists.netfielders.de
[mailto:typo3-english-bounces at lists.netfielders.de]On Behalf Of dave ashton
Sent: 03 July 2006 11:25
To: 'TYPO3 English'
Subject: 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

--
No virus found in this incoming message.
Checked by AVG Free Edition.
Version: 7.1.394 / Virus Database: 268.9.7/379 - Release Date: 29/06/2006

--
No virus found in this outgoing message.
Checked by AVG Free Edition.
Version: 7.1.394 / Virus Database: 268.9.7/379 - Release Date: 29/06/2006