Create a writing style guide

[johnpuddephatt]

One of the aims of the new documentation site is that it be as easy as possible for any member of the Symphony community to contribute.

While this is a really positive move, it does introduce one potential issue: consistency.

While there will always be a degree of quality control during the merging process, things will be much smoother if we have an established style guide we can point potential contributors to.

A couple of example style guides:

Tuts+
Webplatform.org

[nitriques]

This is old, but still relevant: http://24ways.org/2011/front-end-style-guides/

[bernardodiasc]

@nitriques, I also misunderstood the topic at first sight, this is about Writing Styleguides :)

[johnpuddephatt]

Well, it's content style really – which is both written style and presentation!

Thanks @nitriques.

[nitriques]

My pleasure! Feel free to ping me here or on twitter for anything Symphony related :)

[johnpuddephatt]

I've completed a very early draft of the style guide. A couple of key things to bear in mind:

• Some of this is going to be quite subjective. It's a style guide after all. Disagreement with it is very much welcomed
• There is no need to aim for this to be exhaustive from the outset. Instead we should aim to provide some basic guidelines that would steer a newcomer in the right direction, and then add to it over time if we notice common problems in submitted documentation

Draft here on the wiki

[bernardodiasc]

Seems perfect.

Just do not quite understand this:

Limited use of contractions is okay because it makes your writing sound natural, and can add nuance to your writing (don’t typically sounds softer than do not).

[johnpuddephatt]

Contractions = can't, won't, don't, etc.

With that clarification does it make sense, or still not?

[bernardodiasc]

Now does! Thanks for clarification.

[bernardodiasc]

I think I got confused in this part: ("don’t" typically sounds softer than "do not")

The quotes is a suggestion.

[johnpuddephatt]

Ah, yes. Sorry when I drafted it I put the two words in italics, but when I copied it over from Google Docs this was lost!

On 23 Jan 2015, at 23:27, Bernardo Dias [email protected] wrote:

I think I got confused in this part: ("don’t" typically sounds softer than "do not")

The quotes is a suggestion.

—
Reply to this email directly or view it on GitHub #4 (comment).