[TYPO3-doc] Defining official documentation

[Susanne Moog]

Hey Francois,

On 17.04.2010 22:30, Francois Suter wrote:
> 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?

No disagreement. Sounds good :)

> 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.
As there is normally an email address related to the author we should
think about getting an imap email account like documentation at typo3.org
that everyone involved is able to read.

> - 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).

If I understand the code correctly at the moment the first paragraph of
the document is taken as abstract. It will be fun to find a way to
change that without breaking all other manuals ;)

> Opinions?

It's great, I'm pretty happy to see the documentation finally going
somewhere. Thanks a lot :)

Cheers,

Susanne