Create
cancel
Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

Next challenges

Recent achievements

  • Global
  • Personal

Recognition

  • Give kudos
  • Received
  • Given

Leaderboard

  • Global

Trophy case

Kudos (beta program)

Kudos logo

You've been invited into the Kudos (beta program) private group. Chat with others in the program, or give feedback to Atlassian.

View group
Highlighted

Managing writing styles is Confluece

DPK J Community Leader Aug 16, 2019

As number of writes grow in confluence, it become essential to maintain a consistent writing style.

What process do you guys follow to maintain consistency and readability?

Also is there any popular writing style that suites you most?

We over self ask everyone to follow 'Microsoft writing style'.

1 comment

Training and collaboration are the things that have worked best in my experience.

Training should be light but done before letting your author put their paws on a keyboard.  By "light", I really do mean "get them to read the style guide". 10 minutes work.

The place that I was taught this despised some of the MS writing style but loved other parts.  Be brief (where you can), supportive and open, get to the point, write the way you would discuss it in person, always remember the Oxford comma - all very good. 

But they did not like "don't be spacey" because people should write how they feel and let the computers format.  And absolutely avoid contractions because they make English even harder for non-native speakers, and, even the English mostly get them wrong when writing.  I'd like to think I'm ok writing them, most of the time, but I do know I have a complete blind spot for its/it is/it's.

Long sentences with many clauses or conjunctions should be avoided like the plague.  Sentences with one or two clauses are great, three is fine, but when you hit four, start to think about breaking it up.  Over five, and you have lost 90% of your readers.  This is also something I am terrible at, but do try to fix. 

Use paragraphs because monolithic blocks of text are hard to read, and harder to follow.

So the other thing, collaboration, was also emphasised at that place.  Confluence is a wiki, it keeps a history, so any edit can be un-done.  It was the first place where I spotted a mistake in a Confluence page, went to the author to ask permission to change it and got laughed at. 

The whole attitude was "just fix it".  If something is wrong, fix or improve the page, don't ask for permission.  No-one "owned" pages, and everyone was expected to contribute without asking.  Worst case, there's a page history.  If an author did feel you'd ruined a page, that became a talking point about how to improve the content!

Comment

Log in or Sign up to comment
TAGS