[TYPO3-doc] Structure of an official document

[Martin Holtz]

Hi,

>> 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.
well, just let us define the states we need:

1] Warning: do not use admin:password for your backend login
2] Be carefull: if you clear complete cache on an large installation, your 
server might get into trouble.
3] Tipp: Set TCEMAIN.clearCacheCmd = 123 if you have some caching issues
4] Side-Note: joh316 is an dedication to the bible: johannes 3,16

I think that would be usefull.

>> 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.
keep credits +1
cut dedications +1

>> - 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.
TOC before introduction +1

gruss,
martin
-- 
http://blog.martinholtz.de
http://wiki.typo3.org/Ts45min - TypoScript in "45" Minutes
http://wiki.typo3.org/De:ts45min - (auch in Deutsch)