[TYPO3-doc] Defining official documentation

[Francois Suter]

Hi all,

Sorry for being silent these last few days, but I was taken by other 
stuff. I would like to come back to the topic of defining "official 
documentation" because we are nearing the time when new documents will 
be added. So here's a summary of the points that we have agreed on so 
far (or at least that haven't raised a controversy):

- official documents can be recognized by their extension key, i.e. 
"doc_core_*" for core references, "doc_tut_*" for tutorials and 
"doc_guides_*" for manuals covering a given topic.
- official documents will carry an introduction clearly identifying them 
as such, as well as an explanation of the category they belong to (i.e. 
core manuals, tutorials or guides).
- official documents are peer-reviewed in this mailing list and are 
published either by the extension key owner (key ownership probably has 
to be refined).

Are there disagreements up to here?

Further points which I thought about and that we should discuss:

- I would like the author of all official documents to be "Official 
documentation". Individual credits would be given in a new section of 
each manual. Anyway - over time - there are too many authors to mention 
them in the "author" field of the extension IMO.
- In terms of structure we need to discuss where to place the 
above-mentioned credits as well as the category definition mentioned 
earlier. I think it's quite obvious that the category definition must be 
the first thing one finds in the document. There are also sometimes 
dedications that need to be placed somewhere (at least there are 
dedications from Kasper in some of the manuals and I think we should 
leave them). We just need to be careful about the impact on HTML 
rendering, because currently an introduction is automatically extracted, 
so we must make sure that something relevant is extracted instead of 
some standard text (this is not so trivial, because any change in the 
rendering process will impact all existing manuals, including those from 
extensions).
- As suggested by Susanne, manuals should also have a "Further reading" 
section pointing to other manuals, sections to the wiki, etc. In the 
case of tutorials, this would probably be also be a help on which next 
steps to take.

Opinions?

I started documenting most of this in the wiki of the official 
documentation Forge project:

http://forge.typo3.org/projects/show/typo3v4-documentation

I will follow up with a first serious draft of the categories 
descriptions in a separate thread.

Cheers

-- 

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