[Typo3-doc] Wiki people: who's on board now?

[Alex Heizer]

Hello Peter,


Peter Kindström wrote:

> My idea was to do like that during this winter: Release my
>
>"vision", ask everybody for comments (probably without getting
>much comments) and then just start working!
>
>But before I got the time, I changed my mind. I like doing
>things that is useful for others, not only for myself. In this
>case it felt more like doing it for my own sake and then I did
>not feel like doing it anymore!
>(Yes, I´m a little bit strange... :-) )
>  
>
Well, I think we all like the "vision", so perhaps it will live on! :)

>>I agree. However, as a page structure or name on t3.org changes over
>>time, maintenance then becomes a priority for the wiki, rather than
>>writing. My concern is less on what the role of each component is than
>>integrating the components so that everything remains synchronised. We
>>will need all of the current roles to be in the final documentation
>>structure. How do we keep them always synched?
>>    
>>
>
>I think this will "always" be a problem. Because if you make
>*one* framwork that takes care of all documentation/information
>it will be so big that you have to maintain the framework
>instead!  :-(
>  
>
Yes. Then we need a DocTeam Maintenance Team!! :)  I think this would 
need some kind of maintainer for the system, but that should be on a 
typo3.org/com site maintenance level rather than a DocTeam level. I 
think it would be along the same lines of the TER, a component of the 
website/core structure that is maintained independently of the data 
contained within.

>>There is a new
>>project by the typo3.us team to make a new Learning TYPO3 package that
>>guides a new user from having a blank HTML template all the way through
>>to having a fully-running site in T3, including a sample set of
>>extensions. People have suggested "including the MTB guide" or
>>"including the dummy package", or including any number of other existing
>>documentation because it contains a gem of information embedded within
>>it. The Learning T3 package is going to instead take all of the good
>>information and place it in one package rather than just include
>>outdated existing documents. If this kind of thing can be done for most
>>of the other information, we'd be in really great shape.
>>    
>>
>
>It sounds like you are going it the *completely wrong
>direction!?* Are you really going to make yet another document
>for this? And not delete any of the existing ones?
>  
>
Not if I can help it. The idea is to take the relevant information 
located within multiple documents and organize them into a single, 
easy-to-follow document, then burn the existing ones. This is in the 
case of the LT3 project. Other information will go into other updated 
and consolidated documents, as needed, but the idea is to take the 
information that exists multiple times in slightly different variations 
and streamline it into an organized set of logically-ordered documents. 
This way, you don't have a GoLive Integration tutorial that one person 
reads, an MTB guide that another person reads, the FTB which a third 
person reads, and none of them having read the same information about 
setting up a site, and all of them asking a different question on the 
mailing list to solve the same problem, done differently in each site. 
By making a single guide that everyone reads, and getting rid of the 
others it will help customers by putting all the information in one 
place, help the DocTeam by making a single doc to maintain, and help 
those who volunteer or charge for support by providing them a common 
base of knowledge that those asking questions have learned from.

>If so, you are just going to make it worse, because people get
>yet another place to look for information. And I guess that much
>of the information also will be redundant (can be found in more
>than one document) - which is one of the problems today!
>
>No, the way to go is something this:
>- In some cases, split up a document into many smaller ones and
>make each document have one clear subject.
>- Eliminate redundant information - refer to other documents
>instead.
>- In some cases: Move information to other documents, so that it
>have a clear subject.
>- Look at the whole suite of documents and make each document
>have thier own place like in a big jigsaw.
>- THEN you can easily make any package you want: One for newbies
>(with document A, B and C), one for admins (with A, C and D) and
>one for Editors (just A) and so on!
>  
>
That's what I have in mind for the docs. Each new one will be created 
for a specific reason, i.e., to learn how to make an extension. Then, 
any relevant existing information will be looked at and put into an 
outline and logical structure. Then, the new document would be written 
using the existing information, and existing documentation would be 
updated to refer to the single new doc rather than display the info. 
There will, of course, be a transition period where some existing 
documents get their text slowly replaced by references, and some will 
just be removed as all of their information is migrated.  But in the 
end, T3 will be left with a smaller set of current docs that each 
address an issue completely. Any new text will go into the appropriate 
doc instead of an inappropriate one, and if a new doc needs to contain 
information that belongs in another doc, there should be a short (one or 
two sentences) comment about the topic, and a reference to the proper 
doc. In this way, we can have our jigsaw puzzle with only one of each 
piece. :)

>But I really think this will not happen, because it is much
>easier to make a new documents than restructuring the old ones.
>And the more new documents you get, the harder will it be to
>find information or try to structure information...  :-(
>  
>
Not if the new documents have the structure laid out before they are 
started. Which takes more work, and more time, I know. It's not going to 
be easy, but it will be possible. There are some good writers donating 
their time to the US team, so once they get writing we should be able to 
start, and hopefully build up some good momentum.

>Look at installation manuals for an example:
> http://wiki.typo3.org/index.php/Getting_started
>We have 15 different pages/documents about installing and
>upgrading! It would not help much to make yet another one, would
>it? Unless you delete some of the already existing one, of course.
>  
>
Let's start with that example, then. Virgil, you want to take a crack at 
this one? :)

>In this case we should reduce the amount of documents to around
>3-4. Then it would be easier to look for information (if you
>can´t guess what document to read by its title, you have at
>least only 4 documents to read, not 15 like today!).
>  
>
And someone suggested a document index (not just a listing). This would 
be like an index in the back of a technical book:
TemplaVoila: blah-blah manual
Installation: blah manual
Learning TypoScript for AWstats: blah-other manual
et cetera

>
>  
>
>>Hopefully all our dicussions may attract more people to say
>>"I'll help out!" :)
>>    
>>
>
>Yes, but you attract them more if you have a clear goal with the
>documentation and then split the work up in many smaller
>projects - but I think you know that already!  ;-)
>  
>
Yes, there is a lot of work aside from the actual 
writing/editing/maintaining of documents!! :)

Alex