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

[Alex Heizer]

Hi Matteo,

Thanks for your ideas and thoughts.

Matteo Anceschi wrote:

>I agree, there's already a lot of very good documentation.
>My concerns instead are to make the structure of the wiki logical, 
>usable and friendly.
>I do few examples: how can we think that t3 wiki it will be 
>user-friendly when near all the user comments are made on the _article_ 
>pages and not on the talk pages (this is the natural place for them)?
>You think about a "wiki-clone" of the documentation matrix? I disagree: 
>yes, I want to have this, for sure :)
>But: here I'd like to see snippets, suggests, a lot of other things.
>I have a lot of similar thughts, but obviously I wait for "guidelines 
>from the top", actually I'm only a wiki-user :)
>  
>
>
My concerns are more for making all of the documentation available in 
its best form for each target reader. Developers' preferences are vastly 
different than potential TYPO3 customers' preferences. For example, a 
wiki, in general, is not acceptable to most US customers. Since the US 
makes up 50% of the Internet users, and the core T3 team has focused its 
attention to gaining more market share in the US, improving the wiki 
becomes less important than discovering what documentation presentation 
system will work best at acquiring this market. We're actually all in 
agreement about a wiki's strengths, but if a wiki doesn't meet a need, 
we'll have to find a system that does. It meets the need for developers, 
so whatever a wiki does to meet that need will still be required for us 
in one capacity or another.

The last thing I'd want is a wiki-clone of the documentation matrix. I'd 
like to see a way to provide what is good about the documentation 
matrix, plus what is good about the wiki, plus what is good about any 
other system, but integrated so that we can "write once, publish anywhere".

>Remember: we're limitated by the Mediawiki version.
>For example, from Mediawiki 1.4.8 (I'm not sure, but it's surely the 
>case of current Mediawiki version), we can use "patrolling": so we can 
>offer to end-user the last "manually revised" version of a page, instead 
>of the "real last version" (meta.wikimedia.org do this)
>  
>
Still, this doesn't provide a downloadable PDF version, or an offline 
version. Or a version we can pull individual paragraphs out of for use 
on other parts of the site dynamically. Or a navigation menu that 
updates each time you insert a page. Unless these issues are fixed in 
one brand of wiki or another. In which case, we have new options 
available to us.

>>1. Navigation is all-manual. In order to have a page show up as a link, 
>>aside from the Main Page, it needs to be manually placed, linked and 
>>maintained.
>>    
>>
>
>Yes. If you mean that we have to surround a word with [[]] to make it a 
>link, yes.
>But there's not too many maintenance: we wrote a set of naming 
>conventions for pages, and all it's very quick ("wiki") :)
>  
>
No, I mean if I place a new page under the Main Page, if I don't 
manually make a link, located on one page or another, no-one will ever 
know that page exists. Currently, T3 has the capabilities of dynamically 
adding my new page to a menu so that a visitor only has to look to find 
it. If I update the page name, the menu link is updated. If I move the 
page, the menu is updated. I don't have to change my page and then also 
change it elsewhere. If my page is linked to on 341 internal pages and I 
move or rename it, all 341 internal links are updated at the same time. 
I'm not familiar with how a wiki keeps track of pages referenced by 
links, so if it can do this the same way as T3, then this concern won't 
be an issue. But an automatically updated menu is still nonexistent on a 
wiki, regardless.

>>2. Anyone can alter the text at any time. This is good for people to add 
>>documentation easily, but with 1700+ pages and no way to globally watch 
>>each current and new page, constant monitoring can get difficult.
>>    
>>
>
>Yes, it's an effort. But theree's a difference between wikipedia: you 
>can't do "monkey typing" with typoscript: if there's a vandale, it's 
>self-evident, but if there's a contibution with correct syntax, we can 
>rely on (but also we have to verify this later, surely)
>  
>
Can the wiki allow me to monitor all 1700+ pages, regardless? And 
automatically add any new pages to my monitor list? If so, let me know 
because I think I am up to about 100 pages in my "watch" list!! :)

>Yes. This is the big question: the Typo3 "top management" thinks about 
>the wiki as a clone of documentation or not?
>THis is a consideration for, I think, we need a good feedback from them.
>  
>
Regardless, we need the downloadable versions. If the wiki can't provide 
this, we'll need to either abandon the wiki or have two places for 
documentation.

>I used wiki system and read a lot about them. Mediawiki is surely the 
>better implementation and idea now available...in my opinion, obviously :)
>For admin access: I think things will change, isn't it? ;) However, I'm 
>already admin on it.wikipedia.org and I've few more "powers" than a 
>common user, but perhaps this is related also with the mediawiki version 
>we use.
>  
>
Can you export and import entire page trees? If so, this would remove 
this concern, and provide us some options.

>>For a final documentation system, there are many advantages to the 
>>current "write in OpenOffice, export to PDF and pull into a document 
>>site" workflow model, but I also see ways to improve what we currently 
>>have. The documentation repository could be better organized, styled 
>>more attractively (it's not bad now, just a little clumsy here and 
>>there), set up for better PDF generation, and so on.
>>    
>>
>
>I agree, but the question remains the same: what is the role of the 
>wiki? Documentation matrix clone?
>  
>
Exactly. :)

>On wikipedia, we (not I, but obviously in general) use conversion tools, 
>and I think Sylvain  had a look on them: 
>http://wiki.typo3.org/index.php/User:Sylvain#Documentation_related_tools_.28freeware.29
>I think also that if there's a possibility in the nera future to see a 
>OO-Wiki conversion tool, it will be for mediawiki. The activity around 
>mediawiki is huge regarding the other wiki systems.
>  
>
That might be a possibility, but better might be a wiki-to-OO converter. 
This still doesn't solve the navigation problems, but it would offer 
more options.

>
>Alex, I repeat once more (for devs who read, not in particular for you): 
>we need guidelines for the general role of T3 wiki, or (if this is the 
>decision) someone has to tell us "do what you think better". I think 
>that before adding thing or features, we need a direction.
>
>Thank you in advance...and contact me whenever you want :)
>
>Cheers,
>Matteo
>  
>
I agree. I guess part of my questions and concerns grow from being new 
to an existing system (the doc team, not T3 -- I've been using T3 since 
early 2002). The impression I get from the comments I have read and 
heard is that the core team is leaving the doc guidelines up to the 
team. So that means we can take the initiative until they tell us 
differently. I think if we do a good job, they'll be happy with whatever 
we can come up with. (Anyone on the core team reading this can step in 
and refute this at any time *wink wink*!)

IMO, we need wiki-like capabilities for developers and writers, Doc 
Matrix-like capabilities for potential customers and implementers, but 
put it in one system so we can have navigation and content reusability. 
I can't program, so this is just an idea on my part, but this is what I 
see as far as functionality that we'll need to meet all audience's needs.

Cheers,
Alex