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

[Jacob Floyd]

First, just a couple of notes inline. I'll address other things later as I
have time.

On Thu, Jul 12, 2012 at 9:41 AM, François Suter <fsu-lists at cobweb.ch> wrote:

> On Wed, Jul 11, 2012 at 7:30 AM, Robert Lemke <robert at typo3.org> wrote:
>
- dictionary used (New Oxford American?)
>
>  We never discussed having a reference dictionary, but it could be useful.


As far as the dictionary goes, I always use Wiktionary first when looking
things up because I like to support community efforts and I've got a custom
search provider in my chrome browser so that I just type "e[space][the word
I'm looking for]' and I get the English definition. "p" is my shortcut to
look things up in Portuguese (the only other language I'm fluent in).

I'll check around and see if I've got a New Oxford American dictionary, or
what dictionary should be recommended, if any. What benefit does specifying
a dictionary provide?


> - style used (Chicago Manual of Style)
>
>
I just bought a copy of this a couple of weeks ago, so this works for me.
;) What do we do for the people that do not have a copy available?


> - glossary (which terms to use for what?
>
>     Special spelling where multiple options exist)
>
>  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.


It seems that we need a good glossary for all aspects of the project. It's
good to have a glossary so that newcomer's know what we're talking about in
the manual, but it is also important (as Fronçois said) for translations,
and for anyone that wants to touch/modify any core components. Thinking of
DDD, I think we need a really good Glossary that serves the purpose of
having a "Ubiquitous Language" across the project, as well as a "Glossary
of Terms". So, this is not something I can just invent based on what's in
the current manuals. It will require effort by everyone that has
contributed to FLOW3 (ish) to have a more authoritative glossary that is
useful for all parties involved.

If such a glossary is going to be useful in Pootle too, would it be wise to
maintain the Glossary in ReST? Or would a new FLOW3.Glossary package be
beneficial to maintain a kind of living database of accepted terms and
definitions?


> - general rules for structuring chapters and other kinds of text
>
>     (start with an introduction, …)
>
> - other style considerations
>
> 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.
>

There are a variety of approaches to documentation style. I'll review the
Apple docs Robert mentioned, and then I'll comment further on 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.


Where is the general structure defined? (A link to the plain rest files in
git would work fine too).

Cheers,
Jacob Floyd