A Wiki Wah Wild West

As a blogger, influencer and YouTube viral sensation (and exaggerator), every time I write I have to make it count.

Technical writing for work seems to fall into a few categories:

  • Putting words in the place where nobody reads them
  • Adding confusion to people’s day by cryptic messages they cannot follow
  • Overloading people with tons of long-form data they haven’t the time to consume
  • Saying just enough, in just the right places, to provide help

The Bloody Corporate Wiki

Raise your hand now if Confluence is a dirty word in your team. Does your heart sink when you hear the phrases – “I think there’s something in Confluence” or “Can you put something in Confluence for me?”

At the moment, I’m writing a lot of stuff in Confluence… and it’s generally proving useful. Here are some things that help.

  • Structure – use the structure of a document to tell 25% of the story – add a table of contents to the page if it helps – consider the 1-2-3 of writing
  • Structure 2 – use the structure of the wiki – the page tree – to tell the story. Consider having pages whose sole job is to act as a parent for others and show the page tree as the main body of the page
  • Write for search – we don’t want prose, we want search terms. Consider how people will ask for the things you’re writing about and put that in the text.
  • Links and more links – try to avoid great big pages, and instead write single-responsibility pages that defer to other pages
  • Get plugins and use widgets – using native diagrams like Draw.io, Gliphy and PlantUML can tell a lot, and can be easily re-edited when things change (screenshots can’t)
  • Put the extra time in to say it just right – writing just enough can be more work than typing until you’re done.

Some of the best documentation is not needing to document, but to get people to navigate your technical knowledge and your process, you need to provide some structure. A wiki is a great place to do that.

So stick this in Confluence.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s