[TYPO3-doc] Writing Manuals in wiki.typo3.org

[Jakub Tesinsky]

All the reasons you are writing are good but, nevertheless they are not 
saying much about the overal structure of the wiki. Is there something 
like that? From the previous discussions I got the feeleng that there is 
nothing like that. Moreover many of the reasons are either purely 
technical ones or can be achieved in the same way or even in the better 
way be other technical means. To be specific:

> * "extensions" is easy to remember and same path like www.typo3.org

I am not exactly sure if I get the point. Why the fact that extensions 
is easy to remember word means that in every single sentence mentioning 
kickstar on the wiki one should write things like: "...  use the 
[[extensions/kickstarter/manula|kickstarter]] to begin .." instead of 
"...  use the [[kickstarter]] to begin ..

> * "manual" the same word like www.typo3.org

The same reason as before + the reasons I have ritten in my previous 
mail. To select one: what is the plan with the kickstarter page itslef 
than? What is going to be there? Is there already enough content to fill 
up two pages?

> * linking to sub-topics via tagging (example "performance").

This I do not understand.

> * special extension-keys like "sandbox" are no problem

this is a technical thing and coincidence with ONE extension. It can be 
easily solved within one minute in Mediwiki configuration.

> * the special-page "Special:Prefixindex" can list everything with prefix
> "extensions/"

[[Category:Extension]] can do the same and in the better way - it can 
have explanatory text attached. Using Special:Prefixindex for such 
reasons is a VERY BAD idea.

> * it's easy to link to this wiki-page from TER or an OO-doc

It is even easier to link to the [[Kisckstarter]] page alone.

> Problem:
> * We've got to move many wiki-pages (the old name will be a redirect!)

Come on, how many good extensions manual are in wiki? 20? I doubt very 
much. Moreover if you look at the maning of them there are at leas three 
different conventions used and the proposed 
extensions/kickstarter/manual is NOT the prevealing one at all.


Main argument nevertheless is: UNLESS we have the clear plan about the 
wiki structure, the will ALWAYS be this doubd when introducing ANY NEW 
ty pe of page, which is just waste of energy and motivation. And it 
stops people just writing things.

> 
> What you don't know: I'm caring for TYPO3-documentation via wiki since
> 2002 and for the official TYPO3wiki since around 2003/2004.

I fully respect that and if at any stage my ideas should show 
incompatible with yours I give the ground easily. My intention is not 
change you of the community unless there is a will for such a change. I 
only want to show that IMHO there IS a better way to do things. That is all.


> 
> kind regards
> Daniel Brüßler
> 
> 
> 
> Jakub Tesinsky schrieb:
>> This is very difficult question and it can not be answered without
>> having overall plan for wiki structure. However there is no such plan.
>> With introducing any of the solutions we signal that there IS some plan
>> when there is none. Even the fact that someone already involved in
>> writing docs (like Martin) even ASKS such question show that there is a
>> doubt.
>>
>> Without overall plan noone is able to give the right answer - it will be
>> based on personal "like" vs "don't like" or on some very particular
>> experience with some local solution elsewhere in manual.
>>
>> To further explain such difficulty I can show that even the basic
>> question like what should be the first step in the virtual path from
>> words "kickstarter", "manual" and "extensions" are not esily answered.
>> Imagine these hypotetical ways wiki can go in the future with attached
>> arguments:
>>
>> 1. surely docs about typo3 has several distinct parts, like
>> "installation","troubleshooting","extensoins" etc. so it is obvious that
>>  regarding the kickstarter it falls to extensions part. Threfore:
>>
>> extensions/kickstarter/manual
>>
>> 2. we decide that big part of the wiki should grow into the manual which
>> can be easily exported as whole of partially to various formats (like
>> mediawiki manula namespace). The manuals of extensions form a big
>> section of that manual therefore obviously:
>>
>> manual/extensions/kickstarter
>>
>> 3. we decide that typo3 is a modular system and therefore it is good to
>> give different modules their living space in wiki. Supported by the "as
>> flat as possible" argument we supress the "extensions" part and each
>> extension basic module. Therefore:
>>
>> kickstarter/manual
>>
>> Clearly any of these possibilities is followable and therefore we should
>> have stoped here and discuss the overall plan for the wiki. But I feel
>> that currently there is not enough desire/energy/people for such a
>> discussion. If there is, let me know (also please that the mentioned
>> possibilities were not ment as anything like full proposition, i have
>> only invented them to show the wide spectrum of possibilities - there
>> are surelly many better ones)
>>
>> BUT. But what whe should name the pages NOW? Big question. I strongly
>> advocate against introducing some ad hoc structure solely because it
>> will make impression that there is some clever plan and it will confuse
>> readers/contributors more then help.
>>
>> So i advocate to STAY AS FLAT AS POSSIBLE (which BTW is the traditional
>> wiki way) until we have a clear structure plan for the whole wiki. So
>> call the page simply "Kickstarter" and put here everything the aim user
>> of the wiki wants to find here. And than only if it gets too bg and will
>> need separation to two (or more) subparts the decision about to WHAT
>> parts divide and how to CALL them will be much more easier than now,
>> because we will already have the whole document in hand and we will
>> clearly see what are the possible separations. If you really really feel
>> that there should be two documents about Kickstarter RIGHT NOW, than
>> please say WHY. What would be the reason for having more documents and
>> what would be their contents which can not be joined. I am not saying
>> that there is no such reason which would justify that, I am only saying
>> that with this reason in hand it is again far more easier to say what
>> would be the best names for these documents.
>>
>> BTW until now I have spoken about the structure and I only ment the
>> naming structure. Of course that all these structures like 'Extensions'
>>   and 'manual' etc. are beneficiary for the reader, but they can be
>> implemented paralelly and independently with the naming scheme so they
>> can be easily altered, enriched of dismissed in the future. The
>> [[Category:]] tags are just perfect for that and there are many other
>> solutions like lists, separate concept indexes etc.
>>
>>
>> Jakub
>>
>>
>>
>>
>>
>>
>> Martin Holtz napsal(a):
>>> Hi,
>>>
>>> what would be the "right" structure to start with an extension Manual?
>>>
>>> EXT/kickstarter/manual
>>>
>>> T3Doc/kickstarter/
>>>
>>> T3Doc/kickstarter/manual/
>>>
>>> Extensions/kickstarter/
>>>
>>> Extensions/kickstarter/manual/
>>>
>>> i would prefer:
>>>
>>> extensions/kickstarter/manual/
>>>
>>> because we would have no problems with special extension-names like
>>> "Sandbox" and we could have an manual and examples, whislist ...
>>>
>>> What should i do?
>>>
>>> best regards,
>>> martin