[TYPO3-doc] Structure of an official document

[Francois Suter]

Hi,

Thanks for your feedback.

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

I wonder if this is not too much. I tend to think that tips and warnings 
are quite enough. I have never seen (or so rarely that I can't remember) 
books with more than these 2 kinds of boxes. To me these four states 
look too much like a programmer's view of documentation.

I think that having four states makes it complicated for both the 
documentation writer (what state to use?) and for the reader (what does 
each state mean exactly?). I can imagine more states, but they would 
have to have some meaning with regard to documentation. For example, we 
could have the "warning" for very important things to do or not to 
forget, in-depth explanations that give more technical details but that 
can be skipped on a first read and "tip & tricks", which are also not 
vital on first read, but will ease work later.

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

I can understand. Personally I had no wish to make dedications, but I 
was thinking of trying to find a spot where to keep Kasper's dedications...

But I would keep the credits at least. The documents are published as 
"Official Documentation" with the documentation at typo3.org mail address 
for contact, which is totally impersonal. But behind the scene real 
people did the work and I think they should be mentioned, especially 
since we are talking about volunteer work. Being mentioned in the 
credits is an encouragement.

> Next steps
> What's new
> Feedback

OK, good.

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

I also thought about having the category and the introduction before the 
TOC, but I looked through several books and have never seen that 
structure anywhere. I think it would be rather weird, as my guess is 
that a reader expects to find the TOC as the first thing (after the 
cover page and copyright notices), as a quick way to have an overview of 
what's in the manual.

Cheers

-- 

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