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

[Robert Lemke]

Hi folks,

after today's scrum I had a quick chat with Jacob Floyd of our team about how to proceed with the FLOW3 documentation. I'd like to carry this discussion to this mailing list as this is what I'd generally like to do: discuss documentation matters in the Documentation Team and integrate the FLOW3 / Phoenix work more into the overall TYPO3 project.

So, for a start, this might turn out a conversation between Jacob and me, but hopefully it will be interesting for others as well and of course you're always invited to participate.

Now back to the original topic: Style.

The main documentation of FLOW3 (The Definitive Guide, most recent version here [1]) comes with a typical structure for a book of that kind: starting off with a part about the foundations (OOP, DDD etc.), the second part introduces the most important features in a tutorial style (Getting Started). The main part of the book is dedicated to the respective features in a reference style (Manual).

If you look at the existing chapters, you'll recognize that the style varies a lot. Sometimes the reader is addressed directly, sometimes the text is more matter-of-fact. Sometimes the feature is introduces step-by-step, tutorial style, sometimes it is presented clearly in a reference-tone. The stylistic devices used also differ a lot. Some chapters feature an introduction and a conclusion, some don't. The overall style is not consistent.

Some time ago I've read a bit about style and looked into different approaches. What I found fitting best for our purpose was a friendly but no-frills style which easily allows the reader to get the lowdown on the facts. It should be easy to read from start to finish, but at the same time serve as a good reference when you need to look up specific features.

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:

 - 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

While looking for inspiration I stumbled over the Apple Publications Style Guide [2] which I like a lot. It doesn't include all of the above, but it is a good example for a glossary.

A typical guide / reference document from Apple looks like this: https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ObjectiveC/Introduction/introObjectiveC.html#//apple_ref/doc/uid/TP30001163-CH1-SW2

(they also have some good documentation about the HCI style, of course [3])

Anyway, these are just some first pointers.

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.

Any comments are welcome.

Robert

[1] http://integration.flow3org.typo3.robertlemke.net/documentation/guide.html
[2] https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2009.pdf
[3] https://developer.apple.com/library/mac/#documentation/UserExperience/Conceptual/AppleHIGuidelines/HIPrinciples/HIPrinciples.html#//apple_ref/doc/uid/TP30000353-TP6
-- 
Robert Lemke
Lead Developer TYPO3 Phoenix and FLOW3
Co-Founder TYPO3 Association

Blog: robertlemke.de/blog
Get involved: typo3.org – flow3.org