[Typo3-documentation] Don't know how this will go over...

[Coby Pachmayr]

It is with some trepidation that I submit this post.... but I am pasting a
reply to a thread in the typo3.off-topic group... and I thought you might
(or might not) be interested in one newbie's suggestions about the direction
of the newsgroups, wiki, and documentation.

Long live Typo3!!!  Here's my post... bear in mind... these are just *my*
opinions... feel free to substitute them for your own! :-)

> > * RTE -- For Questions, Problems, and Answers
>
> One one hand a good idea, since there are a lot of questions about RTE.
> On the other we would end up with hundreds of NG and the source of the
> problem is not solved.
>

I agree that there might be more NG's... but then again, we could look at
this differently.  There are many different documentation files - not just
one master "Typo3" document.  Perhaps there should be a discussion group /
NG for each document?  Being someone who desperately tries to find answers
in the documentation first -- I find that most of my problems are *with* the
documentation.   Because as a newbie I don't have a real easy way of
identifying what is "wrong" with the documentation, because I *have* to
start with the assumption it is correct.  Yet, sometimes that is a false
assumption... and I am too new to necessarily recognize someone who is
having a "related" problem, because I don't necessarily see the
connection -- especially when there are so many places with which answers
*may* exist (FAQ, List Archives, Newsgroups, other Typo3 sites, Wiki's,
etc.)  And further, it would be great to "talk" interactively with other
users who are pouring over the same document and discuss it more
interactively.

What I'd like to see is the ability to chat with others and say something
like, "I'm reading page X of the Y documentation, and can someone possibly
explain "such-and-such?"

I think if we could focus discussion on the documentation, and really
grasping the concepts ... it would be more like the proverb of teaching a
man to fish, rather than giving him a fish.  ("man" ment generically.. don't
want to offend the women!)  I think if we could make the documentation
clearer we'd see less people asking for specifics of "what code do I need to
do such-and-such"... and we'd see more people asking things like "when the
document says "such-and-such" does that mean "this" or "that"?"

So in summary... I'd like to see (my dream list):

1.) An active wiki -- where documentation is constantly reviewed, marked up,
annotated with version specifics, etc.
2.) A document repository OpenOffice and PDF versions available, with
version numbers, and Status (like extenstions) -- Experimental, Alpha, Beta,
Release Candidate, Final, (Final + Patches/Updates);  Additionally perhaps,
"Dependencies" in other words "Document covers: 3.5.x, 3.6.1".  Then if I
have 3.6.2 I can browse the Wiki to see any relevant updates -- which will
eventually make their way into a future revision of the document.
3.) A Newsgroup to discuss issues related to implementation and
understanding of the documentation.  So if not having found my answer in the
documentation, and not found my answer in the Wiki; then I can (because I've
read the documentation) intelligently post my question in a newsgroup
related to those documents.  Then, even if I'm off-base (perhaps the answer
lies in a different document) someone can simply point that out and say...
"the answer lies in such-and-such a document"

> I'd rather see the RTE issues, once solved, being documented in the Wiki
> (http://wiki.typo3.org) and as soon somebody else comes up with the same
> problem we just point him to the solution with a link. Saves a lot of
> bandwidth and time.
>

The Wikis present their own unique problem... I've noticed that some of the
"finished" documents are simply links to the Document Matrix at typo3.org.
The "assumption" is that these documents are clean and/or without error -- 
which is not always true.  In fact, if we could get all of the documentation
moved to the Wiki, and have a forum for discussion or correction there that
might be one solution.  I posted an "error" two times about the Modern
Template Building tutorials, yet with no response I still have no idea why
my "fix" works -- is it a bug that has already been found/mentioned and I
just never found it? Nor can I currently place my *fix* to help other
newbies because I can't actually edit the document.  I personally wish that
documents would receive the same sort of attention as the coding... for
example, we should have Alpha, Beta, Release Candidate, Final, and Patch
documentation (except in this case "Patch" documentation should be applied
to the final document, with an updated date and/or version number -- for
example, MTB Part 1 v2.2.1 26-07-2004)

I think it will be extremely important though to keep both a Wiki and
Printable format available -- I learn better (as I'm sure others do.. there
are studies) when I read hard copy materials.. especially technical
information.  I have been printing out the documents and placing them into
3-Ring binders... but unfortunately things like the table of contents are of
little value (in larger docs, i.e., TSref) when the TOC page numbers do not
actually correspond to the correct page location.  Don't get me wrong... I'm
not complaining... I'm sure there are those in other OS projects who *wish*
they had as good of documentation.  It's just that I'd like to see Typo3 get
to the next level... where people where Typo3, PHP, and MySQL, etc. are all
seen as "standards" and we that there are professional grade books on the
shelves of our favorite bookstore. :-)


> I don't see how newbies should be able to help newbies but even if they
> could, their time would be much more valuable writing a new article in
> the Wiki about an issues than answering over and over again.
>

See above ... I think the above would resolve this.  In fact, I think this
would make it easier for even Newbies to contribute to the Typo3 community-- 
by ensuring a definitive "path" to follow when trying to resolve problems,
the answer is more likely to be figured out more readily, and newbies can
get up to speed quicker and begin contributing back quicker.

> Jean-Marie

I am replying to your Post -- but I obviously mean the response to be "to
the group" so... hopefully you don't feel I am "arguing" :-)   I'd just like
to have a discussion about this with the group.

Also... let me say again, I love Typo3... and I appreciate the documentation
that we *do* have... but as someone who is technically savvy, and really
earnestly tries to resolve the problems by going through the documentation
... I think I see an untapped area... Typo3 should be for more than just
"programmers" to implement -- the real power comes (and true market
penetration) I believe when you can make it more accessible to the
"technically savvy" not just medium-to-hard-core programmers.  Currently,
most of the documentation as-is-now is probably adequate and makes perfect
sense if you a.) wrote the documentation, or b.) are a programmer and can
dig into the classes and see what is "meant" to happen.

And of course, I don't want to "stereotype" -- some of the documentation is
poor, some average, some exceptionally good...they are not all that bad.
But I think Typo3 as a tool sets a very high standard (and as an OS package
even the documentation is better than most); But I strongly believe we can
raise the bar even higher.

And I'm ready to contribute in any way I can to see this happen.

**I may post this to the Documentation Group also and see what they think**