User:Gorn/Wiki vision
From TYPO3Wiki
This is my vision how some things should be done (I do not say that you SHOULD go this way, I only say that I believe that IF you go this way, than wiki would be very good source of portal documentation which would attract more contributors especially from flanks of "nogurus" than today. Origin of this see: talk page):
The main and the only really crucial point in the vision is that wiki should be aimed to the user of typo3 looking for documentation on typo3. All other points are just separate ideas how to achieve it, they are mostly independent and are not vision themselves, but mediators of these vision.
Contents |
primarily for USERS (seekeng documentation)
This does not mean that wiki can not serve for the people who develop the documentation. Note that project like wikipedia.com all have their "backstage" area which is nevethelss clearly separated from the contents by namespace (http://en.wikipedia.org/wiki/Wikipedia:Namespace, http://en.wikipedia.org/wiki/Wikipedia:Project_namespace). Also the entry points to this "backstage" are NOT prominent on the Homepage neither on subsequent pages so the firscomers FIRST browse the documentation itself and only later whenever they have interest they may obtain the "backstage" information.
If fact I prefer to call it META information rather than backstage because it is more precise. Main namespace of wiki should contain ONLY documentation about Typo3 and there should be a separate namespace for information about Wiki and Documentation developement. There should be some discussion about misson of separate namespaces, but I am not going to deatails right now.
There is another very good reason to make newcomers and middle experienced users feel that they understand what is going on.
flat structure
I think that the BASIC structure of wiki should be very simple and easy to understand. If there are any other structures (trees of documents, tags, directories) they should be PARALLEL to the basic structure ALTERNATIVE. This means that if the user ignores them it means no obstacle nor confusion to him.
Traditional BASIC structure of wikis is FLAT STRUCTURE, with no tree structure or st. like that. To make it more specific there are
bad examples in current wiki
- EXT/kickstarter/manual - this is horrible name for such a important think like Kickstarter. There should be article simply named Kickstarter.
- All "<<Back to " links should be either reimplemented as Categories of at least moved to the bottom of page. By putting the backling prominent position you prioritize one structure in wiki over alternatiove ones which is undesirable. Also there is already enough mechanizms which allow user to "go back" - for example Back button in the browser or "What links here" from the Toolbox on all wiki pages.
- Wiki Homepage: this is a real and I am sure that contraversory topic. I prefer to not to go into details now.
- obstructive rendering of {{Tag|..}} template. See http://wiki.typo3.org/index.php/Template_talk:Tag
good examples in current wiki
- Naming: TemplaVoila is important thing in typo3 and there is a articele named simply TemplaVoila. This is good.
- Frontend editing: this is common concept and there is a article about it (should be expanded).
To close I emphasize again that I am not against structure. In fact the traditional approach in wikis is that there are MANY structures in PARALLEL. Many of them can be implemented using Categories mechanism.
Footnote: Nice example of the fact that the current wiki structure is too complicated is that there are even users who completely ignore it and create their own articles outside this formal structure. For example user Christinapaige2000 who started to write his/her documetation wiki pages. And thought they are still scattered they have already helped me a lot in some questions.
META namespace
I like your idea of hiding the "documentation developers area" from newcomers and I would like to attract your attention to the concept of META namespace which is used in wikipedia. All the information and documentation about typo3 should be in the main namespace and all the information about "writing the documentation" should be hidden and separated in Typo3wiki namespace.
Please do not confuse the "typo3 developers area" and "documentation developers area". The firs surely belongs to main namespace, thought it should be also to some extent shielded from newbies, but this can be easily done.
one topic one article
I think that is a fundamental difference between OO documents and manuals and wiki articles. An article should cover exhaustively one specific topic while manual is more like structured collecion of articles. Also OO documents seem to be aimed to printed version and do not use the links so extensively as is usual in articles or in web pages in general. Wiki should be like the encyclopedia for typo3 user where for each simple topic there is a page.
There should be article for any fundamental concept of typo3 (as a start list one could easily use Glossary list) so than is can be linked from other articles, which can help keep other articles both clean and accesible to newbies. Consider the sentence:
To enable the Admin Panel edit user TSconfig and add admPanel.enable.edit=1 to it.
It sounds pretty straighforward for you, but the beginner can be confused. If you write it like that:
To enable the Admin Panel edit user TSconfig and add admPanel.enable.edit=1 to it.
And if there is a edit user TSconfig article which explains step by step how to edit user TSconfig, may be taking advantage of other articles like user TSconfig, Edit the user record, TSconfig etc...
To ease such linking we need flat and easy naming of articles, which anain bring us to need of flat structure.
simple contribution procedure
The basic contribution procedure to the portal should be as simple as hitting the "Edit" link if the page exist or:
- Create page.
- Edit it.
Apparently there are some workflow rules (http://wiki.typo3.org/index.php/Documentation_workflow) which are good if you want to make quality long OO documents but are obstructive in building the wiki. Quality grows on root s of quantity as has been proven in wikipdia product, who also has its own quality efforts, but ON TOP of free wiki editing. There might be such workflow procedures for longer documents, but it has nothing to do with wiki ARTICLES. Consider the first few points in workflow:
- First you should see if there is a need/interest for the document. Direct your question to the documentation news group.
NO. This is unnecesarry. If I am interested in the subject so much that I am willing to start an article, than it is enough.
* Then you should decide under which section you should put a link to the document. Then ask the DocTeam to put up the link and make the new page. It is not forbidden to make the link and page yourself, but it is considered good practice to ask first.
You can start the article, make it good and only then look for places where to put link to it. There can be even more places and if the article is interesting enough this might be done for you by other people.
* The new document should be put under the Documents in progress section.
Some kind of this is probably desirable - minor flaw is that in the workflow document there is not even a link to "Documents in progress section". I think that simple {{stub}} template or alike might do the work.
Again I emphasize: I speak about ARTICLES, not about OO documents for sum kind of workflow might be desirable. Also there is a crucial thing I have learned in wiki projects: Procedures are popular to suggest but unpopular to follow, due to the effort required to locate, read, learn and abide by them.
