[TYPO3-doc] purpose of wiki [update]

[Jakub Tesinsky]

The problem with the next step for me is that I know exactly how I think 
that wiki should look like if it was meant as "documentation portal" for 
everyone (as we named is few emails sooner). BUT I think that this idea 
is too big step for you and you certainly might not be happy to take it 
(and it would be understandable). Also I do not know whether it is your 
intention to make wiki more as "documentation portal" for everyone. From 
earlier posts I get the feeling that you prefer it more the way it is 
right now, but from latter ones I see that you might like to go this 
way. So probably the best thing I can do is to try to explain my vision 
and you should discuss with your colleagues what the intention with the 
wiki is and who is the aim group.

Before I try to explain the vision I should say that may be it is DO or 
NOT TO DO question. I like very much your idea of "hiding" the 
background. More on that later.

So about my vision (once again, 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):

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.

==primarily for USERS (seekeng documetation)==

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.

==conclusion==

There is probably more than that, but I think it is enough (if not too 
much) for now. I hope that I made my points as understandable as 
possible. If something is unclear, plese ask.

Jakub


> Hi Jakub,
> 
> thanks for your explaination. That tells
> 
> 1. me that we must put some "breadcrumbs" in the wiki, so that nobody
> needs to study 3 years to get the perfect document-editor. I remember
> how the people of wikinews (a subproject of wikipedia) do their
> workflow. They guide the people very good, the technical stuff hides in
> the background.
> 
> 2. we need a better connection between the OO-docs and the wiki. We have
> bridges to bugtracker and extensions in TER now, we also need some to
> documents and back.
> 
> what is the most important next step in your eyes?
> 
> kind regards
> Daniel Brüßler
> 
> 
> 
> Jakub Tesinsky schrieb:
>>> hm. I think about your answer. Could be very important.
>>>
>>> Question: What is your definition of "the documentation developer"?
>> I see "the documentation developer" as some of your friends and
>> colleagues who may have written some extension or is an expert in typo3
>> and is helping to make OO documentation better. Somebody, who knows what
>> is the workflow, where to find things, where to discuss issues, where to
>> grab OO files and where to upload them ... These are the people for whom
>> the wiki serves best and aids them with their incredible work.
>>
>> Hope I have explained myself :-)
>>
>> Jakub
>>
>>> kind regards
>>> Daniel Brüßler
>>>
>>>
>>>
>>> Jakub Tesinsky schrieb:
>>>>> For newcommers: I hope they easily find what they need - and have it
>>>>> easy to make changes and additions.
>>>> I do not think that its that easy ... or at least it was not easy for
>>>> me, because I considered wiki beeing documentation itself, not the
>>>> working place for documentation efforts.
>>>>
>>>> Concernig help: I would surely try to help if wiki was ment as I have
>>>> seen it before - the documentation portal, because I would be part of
>>>> intended audience. However, as I see it now - as working place for
>>>> documentation efforts - I am not sure whether I am able to help without
>>>> beeing the intended user of wiki - the documentation developer.
>>>>
>>>> Jakub
>>>>
>>>>
>>>>> Hi Jakub,
>>>>>
>>>>> I see you now understand it. what about helping me with this?
>>>>>
>>>>> For newcommers: I hope they easily find what they need - and have it
>>>>> easy to make changes and additions.
>>>>>
>>>>> The question-feature: This is not a replacement for a forum, it is a
>>>>> help to find problems or questions within 850 wiki-pages. ;-)
>>>>>
>>>>> kind regards
>>>>> Daniel Brüßler
>>>>>
>>>>>
>>>>> Jakub Tesinsky schrieb:
>>>>>> Thanks Daniel for explanations,
>>>>>>
>>>>>> I understand the purpose of wiki better now. I suggest that it is
>>>>>> clarified on the homepage of the wiki itself, that:
>>>>>>
>>>>>> **It is NOT the documentation portal, it is only working space for
>>>>>> documentation team and the real documentation is placed elsewhere
>>>>>> [link].**
>>>>>>
>>>>>> Comment: it might be obvious for YOU, but clearly not to somebody
>>>>>> new to
>>>>>> typo3 who have just found the wiki - mediawiki engine is commonly used
>>>>>> on web for the REAL documentation - your usage is not as common. Also
>>>>>> the overall structure of wiki homepage strongly suggest that the
>>>>>> wiki IS
>>>>>> intended as documentation itself, it stars with prominent links like:
>>>>>> Getting started or the link Editors is explained like: ... Here you
>>>>>> FIND
>>>>>> documents on how to ... This should be changed to something like:
>>>>>> "Here
>>>>>> we work on documents on how to ..."
>>>>>>
>>>>>> Also if you want to attract help from "just passing" people, you
>>>>>> should
>>>>>> clearly state how they can help you, and what could be their place in
>>>>>> your work flow. If it was the usual situation (documentation wiki
>>>>>> portal) one would expect to browse for the document s/he is interested
>>>>>> in, read it and may be make corrections of expand it. But (if I
>>>>>> understand it) you probably want from "newcommers" only to find the
>>>>>> wiki
>>>>>> document with link to real document and perhaps leave the message on
>>>>>> this wiki page with question (using the question tag). Or maybe
>>>>>> then can
>>>>>> help you with proofreading ... I do not know.
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>> Daniel Brüßler napsal(a):
>>>>>>> Hi Jakub,
>>>>>>>
>>>>>>> We have two steps:
>>>>>>>
>>>>>>> == now ==
>>>>>>> * who does it: everybody
>>>>>>> * collection of texts and images -- what should be changed or
>>>>>>> included
>>>>>>> into the OO-documents what are in TER
>>>>>>> * setting of the state of the wiki-page -- using a tag what you
>>>>>>> see at
>>>>>>> http://wiki.typo3.org/index.php/Teamwork
>>>>>>> ** e.g. draft doc: {{Tag|draft}}
>>>>>>> ** e.g. finished doc: {{Tag|finished documents}}
>>>>>>> * when it's finished and reviewed the doc-owner can change the OO-doc
>>>>>>> and re-upload it into TER.
>>>>>>>
>>>>>>> == soon but still takes some time ==
>>>>>>> * button for import and export on every wiki-page for
>>>>>>> OO-doc-format and
>>>>>>> DocBook-format
>>>>>>>
>>>>>>>
>>>>>>> You understand now?
>>>>>>> kind regards
>>>>>>> Daniel Brüßler
>>>>>>>
>>>>>>>
>>>>>>> Jakub Tesinsky schrieb:
>>>>>>>> May be I have found the key question which can solve my overall
>>>>>>>> confusion. On the Main page of the wiki the mission of wiki is
>>>>>>>> clearly
>>>>>>>> stated:
>>>>>>>>
>>>>>>>> The purpose of this wiki is to optimize the Official
>>>>>>>> OpenOffice-documents by Teamwork.
>>>>>>>>
>>>>>>>> BUT, how this is ahieved? Are there OO documents imported in wiki
>>>>>>>> and is
>>>>>>>> there somebody who implements improvement in wiki to OO documents?
>>>>>>>> Or is
>>>>>>>> there some finer workflow plan?
>>>>>>>>
>>>>>>>> Jakub