[TYPO3] Documentation nightmare

Vincent typo3 at crel.us
Wed Mar 12 00:28:52 CET 2008


First, I want to say thank you to everybody for your kind and helpful
responses.  This gives me encouragement that we will likely get the help
we need from the community to learn the system and overcome problems.
The fact that typo3 has so many users and such an active community, even
though there is such an entry barrer do to the documentation, is a stong
sign of the quality of the software.  I suspect that if the
documentation problems were resolved, typo3 would likely become the
dominant CMS.  


On Tue, Mar 11, 2008 at 12:17:16PM +0200, Dmitry Dulepov [typo3] wrote:
> Vincent wrote:
> > In the TypoScript by example tutorial, there is an example that has 
> > 
> >     page.5 = HMENU 
> >     page.5.1 = TMENU 
> >     page.5.1.wrap = | <BR><BR>
> >     page.5.1.NO {
> >       linkWrap = &nbsp;<font color=yellow> | </font>&nbsp;
> >       ATagBeforeWrap = 1
> >     } 
> > 
> > So I see if I can look up the "NO" attribute in the TSref documentation
> > for practice becoming familiar with TSref.
> > 
> > Naturally, since this attribute is being added to a TMENU object,
> > I lookup TMENU.
> > 
> > No mention of "NO" or "ACT" properties it under TMENU at all.
> > 
> > Finally, I find it under a separate section, 
> >     "Common item states for TMENU, GMENU and IMGMENU series:"  
> > Hmm.  There should have at least been a comment under TMENU
> > pointing me there.  Preferably a link I could click on.
> > 
> > So I go to that section in the TSref.
> > 
> > There, for the "NO" property, it says it is a Boolean value and has an
> > example.
> 
> Not exactly ;) It says "Boolean / (config)". In TMENU you have:
> 
> [Common Item States, see above] || ->TMENUITEM
> 

Thanks.  That helps.

However, how do you know this by looking at the reference?
I saw the /(config) but did not know what it meant.  So, apparently it
means there are also configuration options in addition to boolean.
I still do not know why "config" is in parentheses.   

One thing that would be a big help is if the docs used more cross
linking like a wiki (see wikipedia).  For example "(config)" should be
a link taking me directly to the TMENUITEM page.

So then, can I assume that every property under "10.2. Common item
states for TMENU, GMENU and IMGMENU series:" can be assigned any
property under "10.8. TMENUITEM:", since they all show "/ (config)"?


> I agree it is not obvious, could be better. Do you mind writing a bug report to bugs.typo3.org for documentation?
> 

Is that really what I should do?  Considering I am having similar
problems with such a large percentage of the documentation, I would
probably be sending in constant bug reports :-).  Or should I just start
posting doc problems and suggestions on the typo3-project-documentation
list?  BTW, I went ahead and subscribed and cross posted this to it.

Which brings up another question.  Is there reason only 6 groups are
accessible via the news server, news.netfielders.de?  For example,
typo3-project-documentation does not show up in the list.  Sorry if this
is a little off topic.


> > Is the TSref wrong, incomplete, or out of date, or is the tutorial out
> > of date, etc?
> 
> I understand your frustration. I felt the same many years ago. TSRef is really a ref. I can advise only one thing: download sxw file of TSRef. While you go through TS examples, just search TSRef file for properties. You cannot do it on the web but with file you can! It all will make sense after couple of weeks :)
> 

Thanks for the suggestion.  I may do that in the future.  However the
problem is, I'm not running Open Office right now on my NetBSD
workstation and it would probably be a massive library upgrade, breaking
all kinds of other stuff to try to install it until I get around to
to doing a major upgrade to my OS.  

However, this brings up another issue.  Considering typo3 is an
elaborate content management system with sophisticated search features
:-), why can't I do this on the web?


> > I appreciate all the wonderful work that has gone into typo3 but I just
> > do not understand the primary tutorials and documentation being 4 to
> > 5 years old with all the substantial changes that have been made.
> 
> Changes to docs are collected on the wiki, they should appear in official docs at some point. There is a single person who is allowed to update docs and that person is extremely busy (as most in core team). That's life...
> 
> > Futuristic Template Building - last update: 02.02.2004 15:54
> 
> This one needs a complete rewrite. It is still valid but some things are obsolete and it is easier to write new from scratch than to fix old one. Probably I should be responsible for it as I support TV now but I have no time for it either :(
> 
> > Every document I find is ancient, yet there are all these cool new
> > features mention in the modern releases.  How is a newbe to learn them?
> 
> It's open source, mate :( One way to push it is to pay for it but it is obvious that very few people will want to pay for doc updates.

I know you are spending your time helping me and I appreciate it, so
please don't take offense to what I am about to say.

I often see the "it's open source so don't expect documentation" type
arguments.  Those arguments really bother me.  I completely disagree
when I hear them.  

For open source projects I have written or contributed to, I have always
devoted time to write thorough and up to date documentation for any
release.  Otherwise, it is like saying to the world, "look at this cool
piece of software I have, but you don't because I am not going to spend
the time writing documentation that will enable you to use it".  It is
dangling a carrot in front of you just out of reach.  If you are going
to contribute code to the world, then the documentation is as important
as writing, commenting and debugging the code.  Otherwise, instead of
helping others (which is at least one of *my* primary goals when I give
away free software), it ends up just squandering a bunch of their time
if they end up not being able to use it.

Well... This is just my humble opinion :-).

I keep hearing that people don't have enough time.  However, there is
an enormous amount of time being spent developing typo3 and all the
hundreds of extensions.  There has apparently just been no priority on
documentation.  Up to 5 years old on the official documentation?

Appeal to all the developers:
    Please take a little time off of coding new features and document
    what you have.  Otherwise you don't even have the existing features
    because we cannot use them.

You also should consider that, from an outsiders impression evaluating
whether to use typo3, one would expect up to date well cross referenced
documentation, if for no other reason, because it *is* a CMS, and that
is the very nature of the project.  To manage content.  It looks
terrible for their own content to appear so unmanageable that it does
not get updated for 5 years.

All that being said, if the documentation is good enough that we can get
a site up and running and do not end up aborting typo3 for some other
system, then I certainly will have no problem buying one or more typo3
books if it appears they are up to date enough.




More information about the TYPO3-english mailing list