[Typo3-documentation] The_New_Documentation_Team_Process

[Coby Pachmayr]

> > 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.
>
> Yes, they are not documentations or should be part of it and yet they
> are a source of information where in a ideal world NGs would be just for
> advanced issues and FAQ a problem related and sturctured information
source.
>
These collectively are what I consider to be a "Knoweldge Base", though in
thinking about FAQ's which are done well *could* be considered
documentation... which might be equivalent (replace?) a "Troubleshooting"
section in a manual.

semi-OT:  for whatever it is worth, I came to this newsgroup originally
hoping that it was discussion on specific known problems (technical) with
the documentation.

> > 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.
>
> The problem is that you talk about something way ahead where we don't
> even have the basics. I agree with you that once we have a usable
> documentation (in terms of our new requirements) then we can build on
> that and work with the versions. But before that let's not confuse it
> too much.
>
> E.g. I started with the installation documentation when the version
> still was 3.5.0, now it is 3.6.2. The process is the same, not much has
> been changes (except that the memory limit error is interpreted the
> wrong way). Of course, there will be documentations where the version
> change has more to offer in their specific parts. Then the focus will
> also be obious.
>

That is my point exactly... you realize that because you have experience
with 3.5.0; If I do not have the same experience I cannot tell if the
installation process has changed a little or a lot.  And if I am new to the
product, and I end up having trouble with the installation how do I know if
it my misunderstanding, or something that has changed, or some other problem
(related or unrelated)?  I realize in this example installation may not be a
problem... but as I read through the newsgroups I see that 3.6.2 has broken
many other things related to things like tt_news, and others.

So the problem becomes, I install 3.6.2... but if I follow the tt_news
documentation and it doesn't work, and I'm new to all of this... how will I
know where the problem lies?  If the tt_news (and I'm just using this as one
example) documentation indicated that it was dependent (written?) upon (cms
3.6.0, css_styled_content (0.9), whatever else v.X) and I'm running 3.6.2
then at least there is a trigger that says to me that something must have
changed.

Again, I am running 3.6.1 - simply because I haven't had time to run through
all of the newsgroups to determine all the things that this "minor" 3.6.2
patch breaks; so for my clients, I will be setting up a test server and only
installing cms and/or extensions to the live production server once I have
figured (ensured) that it is stable to me (regardless of its technical code
status) and that I can make it work consistently, and deteremined what (if
any) documentation my clients will need related to it.  [[side note for
those interested: part of my internal "best practices"]]

> > 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?
>
> Just look at
>
>
http://typo3.org/doc.0.html?&tx_extrepmgm_pi1[show]=matrix&cHash=2ca089abb7
>

I apologize... to clarify I meant more as a function of the DocTeam, will
this also be a focus?

> >>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.
>
> Nothing to conquer that one. :-)
>

Score: Jean-marie: 10    Coby: 1    ;-)

> >>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 thought you would. :-)
>

** LOL ** :-)

> > 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
> ...
> ...
> ...
> > I agree 100% ... too tired to go back and adjust my earlier post in
these
> > reply.
>
> OK. I deleted my response above to cut down on reading lines. :-)
>
> > 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.
>
> That's a perfect example of how we also will have to combine some
> information to show the bigger picture. I have no idea how to do it yet
> but I know it has to be done somehow.
>

<strike>Two</strike> One word<strike>s</strike>:  Wiki !  :-)

> >>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.
>
> Nothing to oppose that.
>

Score: Jean-Marie: 12   Coby: 2  :-)

> >>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? :-)
>
> Not really. I sometimes get overwhelmed with own posts and can hear you
> guys moaning (at least elektronically).
>

Perhaps they should be in the wiki? ;-)

-Coby