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

[Jakub Tesinsky]

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