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

[Coby Pachmayr]

Jean-Marie-

Again, I must say I am enjoying this discussion, so I hope you will bear
with me a little longer... my intentions are well meaning, and trying to
both understand, as well as voice opinion - perhaps with fresh eyes. :-)
Hopefully it is taken as such, and not *argumentative*. :-)

Since I was basically flushing out my ideas as I wrote them, I think perhaps
they were too wordy, so here is the more condensed points:

1.)  There should be some way to tie the relevance to what I am reading (in
the documents) to what I have installed, as well as reconciled to what bugs
have been found, verified, and updated (either in code or in documents).

2.) Another point: a "static" document which is 100% accurate is far more
valuable (at least to me) than a "dynamic" document which is 80% or even 95%
accurate -- especially if I am new, a.) I may to recognize that my problem
is related to the 5% which is wrong, which also assumes that b.) I even know
which 5% is wrong.

Another analogy along this point.  A clock in which the hands do not move
(perhaps broken, or no battery) is more accurate than a clock which runs
fast by a little bit each day.  The clock in which the hands do not move, is
accurate 2 times a day... the other clock is rarely accurate.

This is my fear for the Wiki site - as it is already the case now with so
many different sources available for information: Document Matrix, Wiki,
bugs.TYPO3.org (which I only recently discovered), newsgroups, faq, etc.
The attitude thus far seems to be if it has been discussed or mentioned in
one of these places then it is as good as "documented".  I don't necessarily
mean that is the attitude, especially of the documentation team -- as I
understand these are goals you are working towards resolving -- but in my
experience in trying to find/receive help on my problems... which still go
unresolved, because not only can *I* not find my answers, but instead of
getting help -- I get replies to my posts with others with the same/similar
problem... not necessarily with a solution.

3.) I think it is okay to use Wiki, or any other tool... even good old
standby static, hard to update PDF's for user documentation -- the number
one importance is that they be accurate.  And to this end I think the two
movements that need to occur are... review of existing documentation to
bring them into "compliance" and secondly to consolidate the areas that
people are forced to search for answers -- there are just too many right
now.  And in this respect, I even agree that Wiki makes a great choice ...
but as you say, this will have to be monitored.  And as I stated earlier, I
think if the same effort that went into ensuring compliance for the
extensions was placed on the documentation (and it's updating) then things
would be much better.  And again, I think of documentation as being similar
to an extension and feel a similar versioning, dependency, and status system
would work wonders (whether PDF or Wiki)

4.) I happen to disagree that the NG's based on documents would be hard to
handle... but that being said, perhaps not *all* documents -- but certainly
the documents that provide tutorials or examples.  Because I think most
(again those putting in true effort, not lazy) people who work with
something new in TYPO3, whether it is an extension or even TYPO3 itself are
basically trying to learn by the examples in the documentation.  But what
happens when the steps they follow don't work for them?  I personally feel
that the majority (but I could be wrong) of those trying something new are
following documentation in front of them (and if like me, printed from PDF)
and the natural thing currently to do now is to go to the newsgroup to ask
the question.  Consequently my question more than likely centers around one
of these options: a.) Am I following / understanding the documentation
correctly?  b.) Is there a bug / workaround I should be aware of?  c.) What
am I doing wrong?  d.) What am I missing?

Currently these questions are being lost in a *sea* of varied questions,
with people who are at varied levels of skill, and varied versions of TYPO3
and/or extensions -- most of which are there struggling to find the answer
to their problem... not necessarily to answer someone else's.  I think I
would have more luck if I were to post my question to a group of people who
are working with the same document I am, who may have come across the
answer.

Perhaps it will be that when the Wiki is finalized, I will see that this
type of "conversation" about the document can co-exist with the *actual*
documentation without rendering the documentation difficult to follow, read,
or print out.  But my fear is that what we will have is more analogous to
the clock example I mentioned before.

5.) My offer to help with the English grammar within the documents, wasn't
necessarily to make them correct grammatically -- I think that "basic"
English is more than acceptable... in fact, we would all be in trouble if we
had to rely on *my* grammar skills.  But I meant more as a means of helping
to make the manuals correct in their meaning and (hopefully) easier to
follow.  There are often subtle nuances in the English language that make a
*big* difference in understanding the meaning... there have been some times
where I have had to read several times to figure out whether I am *supposed*
to do something or *not supposed* to do something because the wording seems
to contradict itself.  I can't think of an example right now... perhaps
when/if I run into again I will post an example if you think it is helpful
or relevant.  Also... I hope nobody misunderstood my comment about being
"...American and having a reputation to uphold!" -- I was referring to the
reputation of only speaking one language -- *not* writing perfect grammar!
:-)  Hopefully no offense / misunderstanding was taken! :-)

6.)  A summary of sorts -- I see Documentation as the central hub/issue with
which TYPO3 becomes more "accessible" and useable, and consequently a much
more efficient (for development) tool.  And so Documentation should be the
central point in which other areas feed into an appropriate place into the
documentation.  For example:

The bugs.TYPO3.org, the "policy" should be that these items are not just
posted in the bugs.TYPO3.org, but to the extent that they impact
documentation (after all if a feature doesn't work because of a bug, we need
to know that); they should be added (immediately - as much as is possible)
to the appropriate section of the documentation (whether that is Wiki or
whatever).

If documents are available in different formats (OOo, PDF, HTML, Wiki) -- if
there is no set pattern, such as I described in the previous post, then
"policy" should be that these are the *same*.  If one is updated, they
should *all* be updated.  I have noticed for example (quite by accident)
that a document in TYPO3/ext/ was different and had more information than
what was on TYPO3.com.  Things like this should be avoided at all cost.

Also, I think versioning is extremely important -- and I think older
documentation is equally important.  I for example want to keep a
professional operation for my company -- which hopefully will soon begin
converting clients to TYPO3 (If I can ever figure out these silly RTE/CSS
problems).  And because of the state of the documentation, and difficulties
I have faced I refuse to just update every patch as it comes out.  For
example, I barely have a grasp of what I am doing in 3.6.1... and some of my
problems may be fixed in 3.6.2... but I still don't see anyway to concisely
find out exactly what will "break" when/if I install 3.6.2... and what items
that are known problems have been fixed, or are still being worked on... and
more importantly, what if any have been reflected in the new documentation.
I am sure this is even further compounded by those who stay on 3.5.x.  If
the Wiki or other system of documentation does not clearly indicate which
version it applies to, then I may be hopelessly lost because I keep trying
to follow examples that don't apply to what I have installed.

In fact for my company I intend to have a "beta" test server that new
extensions are "figured out" first; then I will roll them over to another
server where I will make the extension a "release candidate"... then when my
internal documentation (for development) is completed, and my client
documentation (fe or be clients) is completed... and I have ensured there
are no other conflicts I will roll the feature out on my "live" server.

** My apologies, I realize now it is not more condensed after all -- but
perhaps more clear? (I hope) **

Again, I appreciate you -- and I certainly appreciate the time and effort
(and patience) that you have taken with me -- and especially to this
newsgroup and for all of your efforts.  Thank you -- without people like
you, things like this could not exist.  Hopefully some things I have said
make sense... and hopefully there is some way I can help/contribute...
though I think my best offer is that of a "newbie" who is truly putting out
good faith effort... and think that I represent a "typical" new person
trying out TYPO3 and going through the "typical" patterns of trying to
resolve problems through documentation and searching.  Some newbies are more
proficient/skilled than I, some are less so -- but in all cases I believe
from reading the posts that the process (and frustration) is the same.

-Coby

"Jean-Marie Schweizer" <jms at marktauftritte.ch> wrote in message
news:mailman.1.1090988255.7956.typo3-project-documentation at lists.netfielders.de...
> > 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.
>
> That might be overlooked in some existing documents but should be taken
> care of in future documents (discussed that at some point in this NG).
>
> > to what I am actually using.  Take tt_news for example:  Not only are
there
> > documents, and tutorials, extention manuals, -- but there are
*numerous*...
>
> This is a key problem that we all run into and our efforts are trying to
> maintain the documents so that most of the information for a newbie can
> come from a document not from the NG. As far as bugs are concerned there
> is also a bug tracker at http://bugs.typo3.org
>
>
>
>
>
> >
> >>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.)
>
> We discussed that before too. I made a suggestions to have some status
> with every article at some point. See :
>
> http://wiki.typo3.org/index.php/Debian_installation_manual
>
> > 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.
>
> This goes into the discussion if we want to keep two sources of
> documents. Wiki and typo3.org. Since there are two main oppinions right
> now only time will tell which one will be the most useable.
>
> > 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".
>
> Yep. Wiki is the place to do that.
>
>
> > 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.
>
> Readybility is not meant for English speaken people (Kasper wrote
> something about that). Since most people DON'T speak english it is not
> so important that what we write is perfect English but that everybody
> understands it. That is by having a basic and simple English, not too
> fancy, even if it has some mistakes in it.
>
> Nevertheless it would be helpful if some natives would be willing to
> proofread as long as they keep the above in mind.
>
>
> > sometimes, because of its flexability it can become an overwhelming
> > entity... much like tyring to find answers only in the NG.  Could you
>
> I don't think that has anything to do with Wiki or whatever you are
> using. If it becomes overwhelming we have to make it easier. It's always
> possible to make something less complicated whre if you need more
> complexity you get into trouble.
> >
> > By accessibility, I don't know if you mean in the context of people with
>
> That people find the information that they are looking for.
>
> > 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.)
>
> Why? What hinders us to have the same guidlines with the Wiki. And why
> should a newbie go first to a maybe outdated or not maintained document?
>
> I rather have them come to the Wiki first (once the Wiki is finished)
> and start there. Like now we keep links to existing and related
> documents where somebody can go if they don't find what they  need at
> the Wiki.
>
> > 2.)  Wiki - This is the "released" documentantion (or new documentation)
> > that is being marked up... possibly by the Documentation team.  In this
way,...
>
> I think I start to understand what you really mean by versioning but is
> that really necessary? Most documents just need an update to every new
> version but don't need to keep the old document that relate to an older
> version. That might be helpful for some extensions but not for most of
> the documents.
>
> Just try to imagine how we should maintain all this not talking about
> writing it first.
>
> > 3.) Document Newsgroups -  I envision having newsgroups for each
"released"
> > (regardless of status: alpha, beta, rc, stable) document.  Think about
this
>
> If we have a NG for every released document I think the whole thing just
> will fall apart. We would be talking about a lot of NG. I don't even
> keep up with all the NG we have now. IMHO not a good idea at all.
>
> I agree that there might be a need for some more NG but defenetly we
> shouldn't make it a rule that every document has its own NG.
>
> >>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.
>
> As Wikipedia proofs, being open doesn't mean a problem. It actually is a
> big asset. Of course there will have to be some maintaners that keep an
> eye on wild writing.
>
> The big advantage of the Wiki to the alternative of SXW team writing is
> that I don't have to explain anyone first how to set up first before
> they can start writing. I just point them to the right link and they can
> start. That's it.
>
> > 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
>
> We all tried and still try really hard. :-)
>
> > 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
>
> That's the goal to make it more accessible.
>
> > 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.
>
> The high learning curve of TYPO3 will always be there even with
> excellent documentation. Some people are just not willing to sit down
> and read they just want to find a quick and easy way and when they don't
> get it, they quit. Nothing will solve that.
>
> But we can help those who honestly try to understand TYPO3 and are
> willing to read. That's why we put many hours of our spare time in what
> we do now.
>
> Jean-Marie