[TYPO3-doc] Structure of an official document

[Susanne Moog]

Hey François (and all),

On 07.05.2010 13:45, Francois Suter wrote:
> Hi all,
> 
> As we discussed recently, there are quite a few elements that must be
> placed in an official manual that would normally not appear in an
> extension's manual. It is important that we define what these elements
> are and where they should be placed.
> 
> I have made a proposal to start the discussion:
> 
> http://drp.ly/XBofK
> 
> What needs to be discussed is:
> 
> - the types of elements: do you think that some are not necessary? On
> the contrary, is there something missing?

You have a warning and a tip box, I'd suggest using the four states as
presented here: http://www.dokuwiki.org/plugin:note

Additionally I don't think and don't like dedications in official
documents. In private ones or ones clearly from an identifiable person I
have no problem with them but I don't think we should have them in
official docs.

> - the names of the elements: are the various elements named appropriately?
Let me cite Patrick ;):

Next steps
What's new
Feedback

> - the placement of these elements: which ones should appear at the top
> or at the bottom of the manuals? Note that - for the purpose of this
> discussion - the table of contents should be considered as an element too.

I'd suggest:

- Documentation Category (Official Documentation + Manual Type)
- Introduction (with "About this document", "Credits", "Feedback" and
"What's new")
- Table Of Contents
- [manual content]
- Next Steps

So we'd have the real manual after the table of contents and the
organizational stuff above it.


br,

Susanne