[TYPO3-doc] Small improvements to official documentation template

[Jigal van Hemert]

Hi,

On 6-9-2010 21:48, François Suter wrote:
> - a 1cm left margin before all text, except the level 1, 2 and 3 headings

I personally prefer left aligned text. Level 1 headings (chapter titles) 
may have other alignments. Call-out boxes are easier to see if they 
stand out (see below).

> - call-out boxes are further indented to differentiate them from the
> text. Furthermore I added a 1cm right margin

Extra margin on all sides make a call-out box stand out more from the 
text. The preferred layout for me really depends on how often they are 
used. If there is hardly any call-out box then it may have a really 
different look (other type-face, borders, background), but if it is used 
on almost every other page then the overall layout starts to become 
rather cluttered. In that case a more conservative look for call-out 
boxes is better in my opinion.

> Note: if it were me I would get rid of all the colors used in the
> headings, which I really don't like, but that may not be an acceptable
> change (trying my luck here ;-) )

I never understood the use of colour in the headings. I wouldn't mind if 
they were gone.

Some more ranting:

For printed documents serif fonts for body text is easier to read.

For relatively wide texts (A4 page width is single column) a line height 
of at least 1.5 times the font size is easier to read. Long lines are 
also hard to read for people with some form of dyslexia.

Is it possible to move to OpenDocument format? I don't know how 
complicated it is to use that for generating the online documentation, 
but at least we would get rid of the outline level problem in paragraphs 
after a heading.

Is there a standard for the tables with TS(config) configuration? 
Especially how to point to other sections, headings of those other 
sections, the little 'caption's below the table, etc.

Is there a standard for images (e.g. screenshots) in the documentation? 
Position, margin, size, caption, surrounding text, etc.

-- 
Kind regards / met vriendelijke groet,

Jigal van Hemert
skype:jigal.van.hemert
msn: jigal at xs4all.nl
http://twitter.com/jigalvh