User talk:Gorn/Wiki vision

From TYPO3Wiki

@Gorn: You now can use the documentation-development-process. See Teamwork. --Daniel Brüßler 15:49, 12 January 2008 (CET)

The following is the excerpt from my emails with Daniel Brussler in typo3.project.documentation list. I leave it here for future reference:

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.

Contents 1 primarily for USERS (seekeng documetation) 2 flat structure 3 META namespace 4 one topic one article 5 simple contribution procedure 6 conclusion

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 .. 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: draft >>>>>>> ** e.g. finished doc: 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