[Typo3-documentation] The_New_Documentation_Team_Process

[Coby Pachmayr]

Jean-Marie ... you had to know I was going to grant you your wish for
feedback! :-)

I am not sure if your points were mentioned as rebuttal to my document,
though I am sure that you must agree with some of it. :-)

Also.. since you have convinced me to put everything in Wiki... I'd be happy
to setup a "Counterpoints" page.  :-)

Anyway, here are some quick comments re: this post:

> 1. There will always be people that jump in and just type whatever they
> think of (similar to somebody who downloads the TYPO3 packages and just
> installs it without reading *anyting* and then posting his problems to
> the NG.
>
I agree this is not a problem.... those kinds of posts are usually
obvious... and with even better documentation they will be even more
obvious. So I agree no need to work to this audience.

> 2. Then there will be other people that search google, look through the
> FAQs, the documentations, the NGs and *then* when they have spent time
> looking for a solution and didn't find it, then they post a question to
> the NG.
>

Here I *think* we agree, just coming about it from two different directions.
There is a middle ground.  A person who is honestly putting in effort to
search through documentation, if that the documentation is in line with the
3 points you mention below, the secondary sources (FAQ, NG, etc.) *enhance*
the documentation ... but I think I want to clarify that my opinion is that
FAQ's and NG's (especially NG's) should *not* be considered documentation.


> An Open Source Community (OOC) will always prefer the latter, even if
> they wouldn't completely ignore the first.
>
> Why?
>
> An OOC is not Microsoft!
> An OOC doesn't have billions to spend on support and documentation.
> An OOC provides an alternative to lincenced and sometimes much more
> expensive solutions.
>

Again, I'm not sure if this is meant as point from my Wiki page.  If so it
is taken out of context.  MySQL, PHP, and Linux are open source... and my
key point in my wiki, is that it is absolutely critical to consider
documentation a part of the code --- not a separate entity that comes
afterwards.  Quality organizations, whether OOC or commercial recognize this
fact.  And I ask the reader to consider what manual for the products (unless
they are totally conceptual) that I mentioned do not have a version number
attatched to them?  For example, I buy a book for Red Hat Linux 9 ... I know
what version it covers.  I still haven't seen anybody acknowledge or address
this diffeciency with the TYPO3 documentation.

> I don't think we will ever accommodate the first but we can help the
> second. Personally, I would be willing to help the first so far till
> they start reading but I have no interest in playing free support just
> because they are to lazy to read.
>

I agree... one interesting question though... is there an intent to offer
documentation within the TYPO3 OOC that is directed to the end user (content
manager)? Or only for the developer / administrator?  Or is that the
responsibility soley of the TYPO3 consultancy that is hosting the solution?

> If we analize TYPO3 (in terms of documentation) we realize that:
>
> 1. A lot of issues are already documented or written somewhere
> 2. They real problem is *not* that it is not there but to *find* it..
>
> And *here* I see where we as a docTeam should put our energy into. All
> the structuring, all the discussions about how to write etc. should
improve
>
> 1. ACCESSABILITY: so newbies can find everything easier.
> 2. READABILITY: so newbies understand what is written.
> 3. MAINTENANCE: so everything is up-to-date.
>

I whole-heartedly agree... but with the addition that there needs to be a
fundamental change in the way the TYPO3 community views the relationship of
the documentation to the code; as I mention above... and expound upon in my
wiki page.

>
> And *here* is the glitch. TYPO3 is not for everyone, e.g. somebody who
> doesn't know HTML and CSS will always have problems with his lack of
> knowledge and will try to find a problem with TYPO3 instead of with
> himself. Same thing if you don't know PHP, MySQL or have no idea about
> apache.
>
> As Michael Stucki told me at the very beginning of my work: " We can't
> help people to learn PHP, MySQL, Linux, Apache, HTML, XHTML, XML, CSS
> etc. We only can help them understanding TYPO3. And in order to
> understand TYPO3 you have to have some knowledge of the above.
>

Here I disagree.  I personally don't think (IMHO) that TYPO3 should be
restricted to only those that know PHP, MySQL, Linux, Apache, HTML, XHTML,
XML, CSS, etc.  How many of these are enough to know?  Do we need to know
all of them?  How much do I need to know of each one?  If I knew PHP well
enough why would I need TYPO3? I personally don't think that knowing these
things should be a requirement.  Perhaps pointing out that the *more* one
knows about these things the easier it will be for them to get started and
make progress.  But again, I don't think we should require someone to know
PHP so that *they* can debug problems with the code... which should be well
documented.

> At first I thought: Well, but it should be possible to write the
> documentation so even the newbiest of the newbies would understand.
>
> Now, I think we should settle on some minimum requirement and improve
> the documentation with that in mind. This should be written on the Wiki
> and accessible to everyone. Because then we don't have many people
> getting frustrated because they don't even start or at least they know
> what they are getting into.
>

I agree with this in concept... but I think setting the baseline might be
difficult to settle on, because it all depends on how each individual
contributor to the discussion views TYPO3 in relation to who "TYPO3" is a
too for (e.g., Programmer or Web Designer?, Individual or Team?)

> Such a description should allow different levels too. Maybe somebody
> just wants to put a simple website up with TYPO3. He doesn't have to
> know a lot. But somebody, e.g. like me, who wants more, who wants to
> improve webdesign and its creation process, has to know more.
>

I agree 100% ... too tired to go back and adjust my earlier post in these
reply.

>
> Here I think Jonathans structure with HOW TYPO3 WORKS at the very
> beginning is good place to write such a definition.
>

Side note: I just thought I'd mention (for whatever it is worth) that the
TypoScript Syntax an In-depth Study was probably one of the key "ah-ha"
documents for me when things started coming together.  I felt it did a
fantastic job of describing the concept behind it all.

> My goal would be to specifiy
>
> 1. Minimum requirements of the person who wants to work with TYPO3.
> 2. Core decissions that are made in this  NG. Subject to change of course.
>

I agree... maybe slight adjustment to #1... maybe a chart or matrix that
shows what you can take advantage of with certain skill set?  In other words
what you need to know to get a basic, built in template to display with
minimum modification (e.g., only changing settings in Constant editor)  up
through creating an XML driven TYPO3 website and writing extensions... or
whatever... hopefully you get the idea.

RE: #2... I am getting ahead of myself here... but one of the suggestions
planned for my wiki document is the creation of a portal tool (or wiki, or
whatever) but some rules of order for presenting an idea... allowing time
for feedback, then placing item up for a vote.


> I KNOW THAT WAS A LOT BUT I HOPE I DO GET SOME FEEDBACK ON THIS.
>
Does this mean you are missing my long posts? :-)