Create a writing style guide

symphonycms / docs.getsymphony.com

The official repository for the Symphony CMS documentation site

2 stars 2 forks source link

Create a writing style guide #4

Open johnpuddephatt opened 9 years ago

johnpuddephatt commented 9 years ago

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 commented 9 years ago

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

bernardodiasc commented 9 years ago

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

johnpuddephatt commented 9 years ago

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

Thanks @nitriques.

nitriques commented 9 years ago

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

johnpuddephatt commented 9 years ago

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 commented 9 years ago

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 commented 9 years ago

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

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

bernardodiasc commented 9 years ago

Now does! Thanks for clarification.

bernardodiasc commented 9 years ago

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

The quotes is a suggestion.

johnpuddephatt commented 9 years ago

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 notifications@github.com 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 https://github.com/symphonycms/docs.getsymphony.com/issues/4#issuecomment-71284345.