[TYPO3-doc] Small improvements to official documentation template

[François Suter]

Hi Jigal,

Thanks for your feedback.

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

OK

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

Since call-out boxes are a new concept in our documentation it's hard to 
say yet how intensively they might be used. However I would expect them 
to be used quite often, once we get into the habit. Do you mean that you 
find the current call-out boxes not "conservative" enough? IMO they can 
hardly any more sober...

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

Next step, maybe :-)

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

 From where do you get that wisdom? I have the exact opposite opinion I 
must say. So I looked up what the wikipedia had to say [1] and it seems 
that there are no studies that proved anything, one way or the other. So 
I would definitely stick with serif fonts as it is used by nearly all 
publishers.

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

Line spacing could be increased a bit, although I think 1.5 may make the 
documents extremely long.

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

This is an ongoing discussion. The switch is not so easy, because there 
are technical implications with the TER, the EM, etc. Rest assured that 
there's a lot of thinking going on here.

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

It's not really defined anywhere. I guess people just copy & paste, but 
it should be described more precisely indeed.

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

We are starting to have guidelines for creating the screenshots [2], but 
not yet for using the screenshots, although I plan to have some.

Cheers

-- 

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

[1] http://en.wikipedia.org/wiki/Serif#Usage
[2] http://forge.typo3.org/projects/typo3v4-documentation/wiki/Screenshots