[TYPO3] Documentation nightmare

Andreas Becker ab.becker at web.de
Sat Mar 15 16:20:17 CET 2008


Hi Daniel

Asking for the level where a documentation should start you simply should
look to any school or university educational book. A dokumentation is
nothing else then a specif book about a specific Extension or Core function.

Didacticts - Learn How to Teach TYPO3 and
Methods - Discover the wide variety of methods to reach the highest
educational level in a certain time.

But first of all you ALWAYS need to pick up a learner (can be newby or prof)
at the point where they just are.
As mentioned we NEED different levels BUT those levels could simply be
building on each other.

Have a ok to all Webempowered Documentation and How Tos, All of them simply
follow this very simple rule. So everytime you read a new tutorial you will
first find task in ALWAYS the same order connected to video Tutorials and
How Tos.

i.e

1. Down load the Extension from TER > Have a look to Video Vid0000 > Read
our How To <link to how to how to download an Extension>
1b. Uploading an Extnsion from your local Computer > Have a look ......
1c. Upload an extension from SVN > Have a look ....

2. INstall an Extension > Have a look ....

...
..
..
 lots of Real Beginner Steps > + a WORKING .t3d for the Beginner with a
simple standard installation.
Newbies want to practice and it is much better to start from a running
system and to copy the steps, then setting up totally new.
By the way MOSTextension Developers who write Tutorials wont be able to
install their own extension only in following the mentioned steps in their
order mentioned in their Tutorial ;-) Try it - You really will be choked how
much manuals and Tutorials are avtually NOT working ie described. In German
we would say it is a real "Armuts-Zeugnis" of TYPO3! and really ALARMING for
an Enterprise Level Software.
Using pipeline those Beginner steps could simply be linked and be some kind
of standard of the TYPO3 GTD (Get Things Done)

Followed by an Adanced Level

10. Get the extension configured and working.
11. Insert Typoscript > Have a look ...
11.

Again another WORKING .t3d should be inserted (solving this - creating those
.t3d an extension developer and its Tutorial Writers will also see that some
steps they try to explain are simply not working like they should.

Followed by a Programmers Level
20. How to modify an Extension
21. How to insert fields, values, change them and so on

Followed by some kind of Technical Reference including the COMMENTED source
code.

To be Number one in CMS you need qualified people and people who love to
work with TYPO3. Ayou can read on and on on this Mailinglist People get
frustrated by the documentation - not by the extension itself. Even Core
Developer, as you can read in this Thread.

Yes Daniel A Tutorial and Manual needs some kind of VERY STRICT guidelines
to follow ALWAYS. Those should start on really NEWBY Level (Those who just
heard about TYPO3 and want to try it)

This (ALWAYS) part can simply be substituted by links pointing to those
really Beginning Tasks. Have a look to the Webempoweredchurch Manuals and
Tutorials and you will see that this is the way you should start always. If
you don't believe it then check the forum on
http://webempoweredchurch.com/support and see how many people are complaing
about tis documentation, actually they are complaining much less and mostly
look for TYPOs or make suggestions to correct steps and in General Thos
corrections get in Place very fast.

If you leave out only one tiny little step on the way to the "Programmers
Section" you will create lots of frustrated users.

i.e. You could solve this with some kind of Requirements. Have a look to OLD
GDR Universitybooks and you will see that most of them have such an
"Requirements Section" before each chapter and a "Summary Section and some
Sumary Questions with Answers at the end " In this Section you have learned
... " If you can't answer this question go back to section xyz and rehears
this chapter..."

That's why i.e. I and my friends studied Aerospace Technology at University
in Stuttgart with about 80% GDR Books (talking about General Physics,
Chemenstry, even Design ;-)

Now in our school we are using Singaporen Math which are following the same
ideas and we do this with great success of our students. Point: If we wanna
have good Manuals and Tutorials we need to have first of all a VERY Good
Stucture, especially Structures continuing in different Levels. from
Beginner to Guru. Thoise who know all about a section will simply jump over
it but even a Guru sometimes get lost and is more then happy to find a
description or video-link of a very simple task. Especially when things get
stuck somehow.

TYPO3 has an EDU Group and hopefully some teachers or teaching staff is in
there. Ask them for helping - and IMHO Peter has already given a very good
structure, which only will need slidly modifications.

Using PipeLine you could reduce Many of these General Steps as People only
would need to point to this "Elementary Task"

I am very happy that this discussion is going on especially as we are
working together with lots of people who have problems even to understand
proper English and if now a Tutorial is "flying on cloud 7" "above all" then
this Tutorial faisl its purpose completly.

"Help to do it by myself" Maria Montessori 1870-1952

Have a nice evening and thanks for this discussion

Andi



2008/3/15, Daniel Bruessler <danielb at typo3.org>:
>
> Hello Dan,
>
>
> > I am going through the same thing you have Dmitry, and am extremely
> > frustrated, like many others. I think there should be a guide, that
> > explains things in order, and gets more complex as it goes, building up
> > in previous material. This will eliminate the problem of doing tutorials
> > without really understanding the logic behind them.
>
>
> thank you for sharing your thoughts. The problem of beginners is that
> the tutorials are mainly for advanced learners or professionals.
>
> What books did you try as beginners-guide?
>
> Would it help you if we had a matrix in TER what shows the grade you
> need for each manual?
>
> I see these steps of learners:
> * beginner/newcommer/newbee/rookie
> * intermediate learner
> * advanced learner
> * advanced/sophisticated
> * professional
>
> Cheers!
>
> Daniel
>
>
> > Dan
> > Dmitry Dulepov [typo3] wrote:
> >> Hi!
> >>
> >> Peter Kindström wrote:
> >>> Look what other CMS:es has got, for example I found this 10 seconds
> >>> after visiting http://help.joomla.org/
> >>>
> >>> -----------
> >>> Official Documentation
> >>>  * The Official Joomla! 1.5 Help Screens
> >>>  * The Official Installation Manual for Joomla! 1.5
> >>>  * The Official User Manual for Joomla! 1.5
> >>>  * The Official Administrator Manual for Joomla! 1.5
> >>>  * Other related guides and reference material ...
> >>> -----------
> >>>
> >>> This is what I believe Typo3 is missing and should be putting effort
> >>> on! And that is what I think the docTeam should concentrate on. Even
> >>> if I think your work also are needed.
> >>
> >> Good point!
> >>
> >> When I started with TYPO3 I tried to follow tutorials, which I did
> >> mechanically without real understanding what I do. Next I tried TS by
> >> example, which I could not understand either. Next I tried MTB and
> >> found that it looks logical but still too complex. FTB was much better
> >> (may be because TV is much easier). But I still it would be perfect to
> >> have small simple tutorials. May be even "How to" or "TYPO3 for
> dummies".
> >>
> _______________________________________________
> TYPO3-english mailing list
> TYPO3-english at lists.netfielders.de
> http://lists.netfielders.de/cgi-bin/mailman/listinfo/typo3-english
>


More information about the TYPO3-english mailing list