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

[Alex Heizer]

Hi Peter,

Peter Kindström wrote:

>
>But my problem was this "process .. until someone complains". I
>felt like I was all alone, so if just one person disagreed all
>my job was undone.  :-(
>
>I think you have better conditions, right now. You have more
>people supporting this work, the issue has been prepared /
>discussed and maybe the "top managements" are ready to support
>this (after the discussions in the "The Right Crew" thread).
>  
>
Well, working with no support is definitely like running up a mountain. 
Very tiring, and you always wonder when you'll get to the top.

Maybe I am just used to asking for suggestions and guidance, then, 
receiving none, pressing on the way I know best until someone complains, 
then turning it back upon them, saying "I asked for comments and you did 
not speak up when directly asked. Now that the work is done, how would 
you do it better?" They usually shut up after that. Perhaps it's just a 
different way of interacting here in the US! :)

>>Well, I think the "manual-only" nature of the wiki (no
>>automatically-updating menus, for example) will always make it hard to
>>make it a permanent final destination for documentation. As a developer
>>tool, it meets the need of easy editability and a linear page structure,
>>but when you have multiple cross-linked pages, not having a good
>>navigation structure can be a hindrance.
>>    
>>
>
>Yes, that's why we said the wiki is just a workspace!
>But I think the most important thing is to have a good and
>logical structure. And the same structure on typo3.org as on the
>wiki. That could be an (easy?) step towards a unified way of
>managing documentation (like your suggestion with the
>documentation framework).
>  
>
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?

>>Yes, yes, yes! There is an amazing amount of information, but it was
>>posted even today on another mailing list that when compared to other
>>CMSes, the documentation was the major criticism. The work that everyone
>>has all done so far deserves more respect than that, and what I hope is
>>that we can consolidate, review and present it in such a way that we get
>>no criticism for it. Often the criticism is of the "this info isn't
>>available" nature, even when it's been available for 3 years! The real
>>criticism is "this info can't be found".
>>    
>>
>
>
>That is true!
>But what are you/we going to do about it? How do we make it
>easier to find the information? Note that I wrote "information"
>not "documents", because I think this is the problem: People can
>easily find *a lot* of documents, but they still don´t find the
>information they look for!
>  
>
Yes, exactly. That is why I also used the word "info". :) But I think 
that is a separate issue, but tied into a complete solution. The wiki 
has information, t3.org has information, 100,000 personal websites have 
information, how do we make sure the information on a CIO's desk is the 
exact same as in the "workspace", and that it is the most appropriate 
information for their need, written in the best language?

>My idea is that this is mostly a structuring problem. Documents
>contain information that you don´t expect (like this excellent
>newbie explanation about the BE interface in "Inside Typo3"
>under the header "Core Architecture"). And other documents does
>not containg what you expect (none of TSConfig, TSRef or TS by
>example contains any basic explanation about TS).
>  
>
There's a newbie explanation about the BE interface in "Inside Typo3"??  
Good example. And something that needs to be addressed. 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. Now, if only 
there were 36 hours in a day, and 12 days a week... ;)

>This is just examples (maybe not that good) but I think they
>point out one key issue: We have to organise / structure
>documents better to help people find what they want. This is of
>course a huge task, but in the long run IMHO it is necessary to do!
>
I agree, and it will certainly have to be an investment in the 
beginning. Hopefully all our dicussions may attract more people to say 
"I'll help out!" :)

Cheers!
Alex