[TYPO3-doc] New documentation categories

[Francois Suter]

Hi all,

This is a follow-up to the "A vision for the TYPO3 documentation" 
thread", going into more details about the documentation categories that 
I envision. As a refresh, here's my proposal for three top categories:

- Core manuals: more or less the existing ones, in-depth documents 
describing the inner workings of TYPO3 or extensive references about its 
API and languages (like TypoScript).
- Guides: manual covering some topic extensively, that can be used as a 
reference when working with that topic. Examples are security, 
administration, editing, etc.
- Tutorials: step-by-step manuals that teach some aspect of TYPO3. Most 
obvious such manual: Getting Started, but also templating (replacement 
for MTB and FTB).

The first way I would distinguish between these three kinds of documents 
if by extension key. We already have "doc_core_*" for core 
documentation. I would like to have "doc_tut_*" for tutorials and 
"doc_guide_*" for guides. To enforce the official quality of such 
documents, those keys would not be available for registration via the 
TER. One would have to apply to get one. Looking at what "doc_tut_*" 
exists out there currently, this should not be a big issue: they are 
either very old manuals by Kasper or translations thereof. Hopefully we 
can get those translators who are still motivated to translate the new 
manuals and render the old ones obsolete.

Then of course each of these categories would have its own list/page/tab 
on typo3.org.

Daniel suggested to use different icons and I think it's a nice touch, 
although not essential. The hard part is finding icons that mean something.

A standard introduction paragraph at the beginning of each document 
would probably be a good thing too.

Apart from that I don't think that the documents should look different. 
They should all be clearly recognizable as "official manuals". That 
being said it will probably make sense to have specific styles for some 
categories, for example "tips & tricks" call-out boxes in guides, or 
"important points" boxes in tutorials, etc. This is already going into 
too much details, we first need to get some content ;-)

What's your opinion on this?

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch