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

[Coby Pachmayr]

> Thank you for your post. I'm trying to sum up what I understood from
> your post.
>

I am always happy to post!  I always have an opinion... just ask me! :-)

> Your are expressing pretty much the problem that we try to solve in the
> docTeam. The Wiki is very new and not up to it's fullest potential yet
> since it lacks from enough content.
>
> With the Wiki we do have everything we need to satisfy the need of
> newbies and others. That is, we have the tools... We have ML/NG,
> documentation section at typo3.org with OOs and PDFs and the Wiki. The
> questions we should be asking is how we could use those tools more
> efficiently or how do we write so everyone is satisfied and gets
> something out of it.
>
> We had a lot of discussions about how to write, how to structure etc.
> already in this NG. A lot of your suggestions have been addressed and we
> are coming up with a solution at some point, that I'm pretty confident.
>

It is actually because of some the past discussions that I read that in this
NG (and other Typo3 NG) that made me feel compelled to add my thoughts to
the process.  It seems the one thing overlooked (at least to my
understanding) is a connection between the document and core/extenstion
versions that they affect.  I may be missing something ... I do see dates on
the docs, but I have no easy way (without making my own spreadsheet perhaps)
to understand exactly where any particular documentation stands in relation
to what I am actually using.  Take tt_news for example:  Not only are there
documents, and tutorials, extention manuals, -- but there are *numerous*
posts that indicate this bug, or that bug, etc.  Some refer to things that
get better with this change or that change, and still in other places things
that break when you add this extension, or make this change etc.  As a
newbie... I have no idea how to reconcile all of these things, and I don't
know if the parts that aren't working for me are related to my lack of
experience with Typo3, misunderstanding the documents, or some known (or
unknown) problem that by some miracle I happen to find through no fault of
my own.

> The problems that we try to solve (in a nutshell):
>
> 1. Structure
> 2. Readability
> 3. Maintenance
> 4. Accessbility

My suggestions [in a nutshell :-) ] is that there be some sort of
"versioning", "dependencies" and "status" (i.e., alpha, beta, stable, etc.)
when documents are released (SWX and/or PDF) ... and use Wiki to create, add
to, modify documentation etc.  So for example, the Document Matrix (should
be kept as a central, print ready document repository) would contain
"stable" documentation - and include exactly what versions that it affects
and/or is dependent upon.  These documents will have gone through rigourous
Wiki-ing to ensure that all is up to standard before being released.  That
being said, of course there will be document "bugs" just as there is with
many code releases... but now we can easily create a Wiki for "Document
Bugs", which would be the place for people to place problems with the docs
before the next "release".

I am also willing to help in anyway towards making this happen, if it is a
simple function of available time.  Also, I would love to help and possibly
"edit" the text to be grammatically correct, though I only speak English...
I'm American and have a reputation to uphold! :-)  Sometimes things are hard
to understand when there are subtle differences in language.  This isn't
meant to offend anyone who has written the documentation - so I hope none is
taken - but towards your goal of "readability" this would go a long way.

I also believe that the structure I mention above would make the maintenance
of the docs *much* easier.  Wiki is *great* tool -- but IMHO I don't think
it is what we call a "silver bullet" solution - that will take care of
everything.  It works great for programmers, because the documents must be
very structured - which if done correctly can add to readability... but
sometimes, because of its flexability it can become an overwhelming
entity... much like tyring to find answers only in the NG.  Could you
imagine if that were the *only* source we had? (Perhaps it used to be that
way, and I am lucky now!)  But if you don't know all of the previous
conversation, or the how the date and time of the message relates to the
particular version you are using now it can lead you on a wild goose chase.

By accessibility, I don't know if you mean in the context of people with
disabilities (like using CSS code for accessibility); or if you mean how
easily the documents are available.  If it is the latter - then, I think too
this would make not only the documents more accessible, but TYPO3 more
accessible on the whole.  I think we need a clear "road map" (not just of
what documents to read first), but a clear road map and definition of what
should be posted where... and in an ironic way, I think *limiting* access to
the Wiki and "stable" documents would make accessability even better.  I see
a structure something like this:

1.)  Document Matrix (PDF / SWX / HTML) - These are "released" documents
which follow strict(er) guidelines as mentioned above, related to
versioning, dependencies (core/extentions plus version numbers of each),
status (alpha, beta, release candidiate, stable, etc.) This should be where
newbies go *first* because the documentation has been reviewed, written
clearly, etc.  (unless of course it is alpha, beta, etc.)

2.)  Wiki - This is the "released" documentantion (or new documentation)
that is being marked up... possibly by the Documentation team.  In this way,
we can limit Wiki posts about "bugs" affecting the documentation or
tutorials, especially in the *wrong* place or somewhere that makes the
document less readable.  In fact, perhaps for each released document the
"Known Problems" section would be the place where all addendum and changes
are made... until they are incorporated into the next "release" properly
verified and formatted correctly.  You could also make changes directly into
the Wiki to save time for when the document is to be released- but some sort
of formatting (different color?) should be applied so that it is clear to a
reader that this has changed from the "stable" or previously released
document.  The Wiki is where the newbie (who is following directions and
searching for the answers) would go after reviewing the previously released
document... especially if what the newbie (or non-newbie) tried in the
documentation didn't work as expected.  The next logical place would be to
turn to the "Known Problems" section of the documentation and see if there
is an annotation there; if not, go check the Wiki documentation and see if
there is an annotation in the "Known Problems" there. And if not... step #3

3.) Document Newsgroups -  I envision having newsgroups for each "released"
(regardless of status: alpha, beta, rc, stable) document.  Think about this
for a second... why do we have NG's?? Sure some for discussion... let's keep
a "sandbox", "general", etc (see #4) but the primary purpose (as I see it
anyway) is as another source for people to try and resolve problems.  So
presumably, a person who is genuinely putting forth the effor to find their
answers in the "documentation" (released, and Wiki) still just may not get
what is going on.  If most are like me (and they may not be which might be
the flaw in my thinking) then they probably have the documentation sitting
in front of them, pouring over the TS code, and painstakingly trying to
figure out why things just don't work.  If the documentation was "stable"
than more than likely this problem would be limited, because the newbie is
probably (again like me) just trying to figure out the basics by following
the examples; and not trying to write their own PHP class first thing.  So
then, most likely it is probably a function of the person simply not
understanding or misunderstanding what they are reading;  So the best place
to ask your question would be in a NG for that document.  You might ask
somthing like... "I'm having a hard time making the example on page XX work
in the RTE documentation version x.x.x, running typo version x.x.x, and
HTMLArea version x.x.x here is my code, am I missing something?" or
whatever... I'm sure you can think of numerous questions.  But at least now
we (the newbie and those who are helping) be able to be on the same "page"
and understand better how to help.

4.) Conceptual Newsgroups - Of course all of the above dealt with making the
documentation better structured and a more reliable source for newbies, so
that in fact it should limit the number of questions (from those newbies who
are actually reading the documentation).  But there are of course
developers, designers, etc. which would still need their own particular
groups - but now these would be filled with more "conceptual" conversations
and problems .. and less problems that are simply a result of unclear
documentation.

> We can solve those problems with the Wiki, a solution for download and
> offline printing (not necessarly OOo/PDF at typo3.org) and the ML/NG.
> Adding a chatroom might help but I think we help more by focussing on
> the documentations for right now.
>

Only problem that I left out above about Wiki's is that if you open access
to everyone, links can quickly make the document less "readable" and hard to
actually find your answer.  IMHO anyway.

> The beauty about the Wiki is, you don't have to suggest and hope that
> anyone will take your suggestions and change something, you can do it
> right away.

See above.

> So, if you have a clear picture in mind, how you want to
> have a certain documentation, just write it. Check with Peter where to
> put it (since he takes care about the structure) and post here if you
> have any other questions.
>

Perhaps Peter is monitoring this, and anyone else, please feel free to
comment.  These are just my opinions, as one newbie who has tried *really*
hard to be self-sufficient with the given documentation -- and as good as
the docs are, I just still see a next phase that could make Typo3 more
accessible to designer/developers.  No software this powerful should ever be
billed as "plug-and-play" and that is not my attempt... but I'd sure like to
help limit the number of people who post starting with "I'm pulling my hair
out" or "I'm about to shoot myself".  And if we can keep just one newbie
from quitting on Typo3 then there's one more person to contribute and
evangalize the product to raise awareness and take this product to the next
level.

> PS: I know there is more to write but I'm blank right now. So forgive me.

I appreciate the response, and hope we can dialog further on these points.

-Coby