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

[Daniel Brüßler]

Hi Jakub,

I read carefully what you wrote and I'm still shure that this is the
best way:

extensions/kickstarter
for "the" starting page

and
extensions/kickstarter/manual
for the manual what can exported as OO-doc

Reasons:
* "extensions" is easy to remember and same path like www.typo3.org
* "manual" the same word like www.typo3.org
* linking to sub-topics via tagging (example "performance").
* special extension-keys like "sandbox" are no problem
* the special-page "Special:Prefixindex" can list everything with prefix
"extensions/"
* it's easy to link to this wiki-page from TER or an OO-doc

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


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

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