[TYPO3-doc] purpose of wiki

[Daniel Brüßler]

hey great, Jakub!

give me some time to read. ;-) In the morning I'm leaving for CeBIT,
back at monday.

kind regards
Daniel Brüßler



Jakub Tesinsky schrieb:
> 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