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

[Jean-Marie Schweizer]

> 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