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

[Alex Heizer]

Hi Peter,

Peter Kindström wrote:

>This have all been discussed before and we came to no clear
>conclusion. Mostly it is up to the current active people in this
>list / in the wiki to make what they want...  :-(
>Unless something happens that makes the "top management" guys
>interested in this.
>  
>
True. I know they're really busy with their own work, so I'd be 
interested in seeing how we could help lighten their load too.

>But I can give you some feedback on old discussions mixed with
>my own ideas:
>
>* It all begun with the wiki as *a workspace* for documents and
>the docTeam. We never solve the problem about how to manage
>(versions etc) finished documents.
>
I agree with that purpose. And, unfortunately that problem.


>* The wiki has big advantages
> - it is easy to write there
> - it is easy to let many people contribute/work together
>
>* And it has disadvantages
>  - spam
>  - hard to control
>  - no download possibilities
>  - maybe not so nice looking printout
>  
>
Agreed for both.

>* There have been plans to upgrade the MediaWiki version for a
>long time now...
>
>* There has to be some guidelines about working with / in the
>wiki. Like how to use the Discussion tab, versioning etc
>But I don´t thing these guideline will come from the "top
>management" guys. Unless noone can persuade them...
>  
>
I sort of get the impression they don't see a fundamental problem, and 
so are leaving the details up to whoever is in charge at the time. I say 
write/revise any current guidelines and proceed as though that's the 
real deal until someone complains. You can only solicit feedback for 
just so long before you realise the project is going nowhere. :)

>* Instead of trying to get the grip of all the wiki and all the
>documents on typo3.org, you should concentrate on a smaller
>part. Make some sort of official documentation for Typo3.
>  
>
Well, with my team, we're operating under the pretext "it all needs to 
be done, start with the important stuff and just keep going!" Our main 
focus is making sure the most important and frequently-used docs are at 
least translated properly, with good spelling. Over here in the States, 
that's one of the biggest complaints about the documentation; the poor 
spelling and grammar. Some out-of-date docs will need to have the 
determination made whether they should be just edited and updated, or 
completely rewritten. If a doc was written back when version 3.5 was 
current, there may be a lot of fundamental things that will need to be 
scrapped and written new. For example, information about the Extension 
Repository.

>* I think we also should concentrate on english documentation.
>Otherwise the task will be HUGE...
>  
>
"Otherwise"...?  ;)

>* I have the feeling that the wiki was set up by some
>enthusiasts without much contact with the Typo3 "top
>management". Therefor I feel the "top management" has always
>seen the wiki as some sort of playground.  :-(
>
>* My idea was to "integrate" the wiki and typo3.org
>documentation pages in some way. First by having the same
>structure and second by starting to link between them.
>  
>
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. For example, having to always 
go back to the Main Page and follow one link, then another, then 
another, then another to get to a different inside page from the one you 
are currently on can get confusing or tiresome compared to a DHTML 
dropdown menu, or even a persistent left navigation submenu that expands 
to show the current sublevel. On the surface, the difference can be as 
simple as being able to see the same structure from anywhere on the 
site. With a wiki, you can't easily tell from a 4th-level page that the 
structure is the same as on typo3.org. Again, this isn't such a problem 
for a developer, but once you start getting web design consultants or 
in-house IT staff looking for a specific piece of information, it can be 
a deal-breaker since they don't have the same sensibilities as a developer.

>* I don´t think TIMTAW is ready to replace the wiki yet. There
>are some usability issues left. It has to be as easy as a wiki
>to be useful!
>
>* Good documentation is important for users. And we have a lot
>of it! It "just" has to be organised (both inside/between
>documents and as a whole) and managed in a good way.
>(Example: You find information about how to enable the admin
>panel in three different documents - all have a little bit
>different information!)
>  
>
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". Since the people who are going 
to be using/spreading T3's use need to find the info in a completely 
different way than a developer, the important thing is to find the best 
way to present that info. That way, use of T3 will grow, and the 
developers will have jobs next year. :)

>* Don´t abandon the wiki until you have a replacement that is
>proven to be as good as, or better, than the existing wiki !!!
>  
>
Again, developers like the wiki, so I can't imagine it ever being 
abandoned, except when being upgraded to the next version of the wiki. 
But potential customers hate it, at least in the US market. So finding a 
good workflow will be key to meeting the needs of both types of users so 
that the documentation doesn't get stagnant.

Thanks,
Alex