[TYPO3-doc] Documentation style for FLOW3 / Phoenix docs

[François Suter]

Hi Robert,

Good to see you here ;-)

> What we should start to establish is a style guide which contains
> (over the time) all important facts enabling new members of the team
> to write good documentation which fits into the general style. It
> should contain information like:

I think this is an interesting topic, especially for new manuals (like 
all the ones for FLOW3).

> - language used (American English) - dictionary used (New Oxford
> American?) - style used (Chicago Manual of Style) - glossary (which
> terms to use for what? Special spelling where multiple options
> exist) - general rules for structuring chapters and other kinds of
> text (start with an introduction, …) - other style considerations

The TYPO3 official manuals all use American English. We never discussed 
having a reference dictionary, but it could be useful. Neither do we 
have a glossary, but that would definitely be good, especially since 
such an effort is under way for translations on the Pootle server.

The writing style tends to vary. At least for me, I know that I keep 
mixing between passive voice (inherited from my scientific background) 
and a direct style.

We defined a general structure for manuals, but not at chapter level. 
What with the current migration to ReST, I don't think I have an example 
visible somewhere.

> How do we proceed? I'd love Jacob (+ volunteers) stick their heads
> together and come up with a first simple draft for a style guide
> which allows us (yes, even developers) to produce some much more
> consistent documentation.

I think this endeavor is worthwhile. The main problem we will face IMO 
is that we have precious few English native speakers at hand. At least 
there are none among the "core" documentation team, nor are they 
professional technical writers.

It would be great if some people were inspired by this thread and would 
like to contribute to this.

> http://integration.flow3org.typo3.robertlemke.net/documentation/guide.html

This gives an error:

FLOW3 requires the PHP setting "date.timezone" to be set. (Error 
#1342087777)

Cheers

--

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