Blog Archives

Out of print: “Confluence, Tech Comm Chocolate”

A few months ago, I asked my publisher to take my Confluence wiki book out of print. The book is titled “Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication”. It takes a while for the going-out-of-print process to ripple across all the sources of the book, but by now it seems to have taken effect in most sellers.

solong_300pxWhy did we decide to take the book out of print? I’m concerned that it no longer gives the best advice on how to use Confluence for technical documentation. The book appeared early in 2012, and applies to Confluence versions 3.5 to 4.1. While much of the content is still applicable, particularly in broad outline, it’s not up to date with the latest Confluence – now at version 5.6 and still moving fast. I thought about producing an updated edition of the book. But because I don’t use Confluence at the moment, I can’t craft creative solutions for using the wiki for technical documentation.

Here are some sources of information, for people who’re looking for advice on using Confluence for technical communication:

  • If you have a specific question, try posting it on Atlassian Answers, a community forum where plenty of knowledgeable folks hang out.
  • Some of the Atlassian Experts specialise in using Confluence for technical documentation. The Experts are partner companies who offer services and consultation on the Atlassian products. The company I’ve worked with most closely on the documentation side, is K15t Software. I heartily recommend them for advice and for the add-ons they produce. For example, Scroll Versions adds sophisticated version control to a wiki-based documentation set.
  • AppFusions is another excellent company that provides Confluence add-ons of interest to technical communicators. For example, if you need to supply internationalised versions of your documentation, take a look at the AppFusions Translations Hub which integrates Confluence with the Lingotek TMS platform.

A big and affectionate thank you to Richard Hamilton at XML Press, the publisher of the book. It’s been a privilege working with him, and a pleasure getting to know him in person.

For more details about the book that was, see the page about my books. If you have any questions, please do add a comment to this post and I’ll answer to the best of my knowledge or point you to another source of information.

The Making of “The Language of Content Strategy” (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

The Language of Content Strategy is a book by Scott Abel and Rahel Anne BailieIn this session at STC Summit 2014, Scott Abel discussed the content strategy, tools and technologies behind the making of the book.

Problem statement

Time, money, skills and experience are in short supply. Hand-crafting content is expensive, time consuming and not scalable.

The demands of the audience are changing. People use social media, rather than going to a specific website to gather information.

To meet the demands of content delivery today, we need to adopt manufacturing principles. The is made possible by content engineering: The application of engineering discipline to the design and delivery of content.

Case study: The making of  The Language of Content Strategy

In this session, Scott will show us how he and Rahel created a book, an eBook, a website, and a set of learning materials, from a single source, without breaking the bank. They did it by harnessing technology and crowd sourcing.

Scott talked about the differences in approach between technologists and editorialists. Conflict and time wasting arise because of a lack of a common language. Rahel and Scott wanted to craft a solution: A crowd-sourced book about content strategy that is both a case study in content engineering and a practical example of content marketing.

Setting up

The team started with careful analysis of the educational landscape, contributors, and more. Then they defined the content types they needed.

  • The smallest unit of content they would create would be a term and definition pair.
  • Another content type is an essay of 250 words.
  • Then there are contributor bios, statements of importance, and resources.

For the authoring environment, the team selected Atlassian Confluence. It’s a wiki with support for XML content re-use.

They also chose a gimmick: 52. The project included 52 terms, 52 definitions, by 52 experts, published over 52 weeks, and one of the output formats was 52 cards.

Then they selected a team of experts: the best and brightest in tangentially-related fields.

Other roles and responsibilities: markup specialist, editor, indexer, peer reviewers, and a graphic artist.

The source data

The source was authored in Confluence wiki. The content types are clearly labelled: Biography, importance statement, topic name, definition, etc.

The output

In the various output formats, the content is structured differently but still consists of the various topic types. For example, in the printed book every chapter is two pages long, and consistently structured. The eBook format is slightly different, as are the website format and the flash cards learning format.

Each Thursday, one chapter is automatically published. The web output also contains audio files, photos, and additional resources that are not contained in the book.

The advantages of a future-proofed content strategy

The team was able to add content after the fact, such as the audio files for accessibility. The content strategy was designed to future proof the content, so the team was able to adjust to challenges and opportunities. And the strategy is repeatable. Now that it’s been done, it can be done again.

Scott told an amusing story of how he disobeyed his own rules, and tried to create another channel by copying and pasting instead of using the single-sourced content. A marketing person asked him to create a slide deck from the content. He was on a plane, without WiFi, so decided to do it by cutting and pasting. Needless to say, this didn’t work. By the end of the flight he had only 13 slides of the required 52, and had run out of laptop battery!

Cost

The cost of the project came in at under $10,000USD.

  • Approximately $4000USD forgraphic design, indexing, editing, markup assistance, audio tracks and hosting, the URL for the first year, and site hosting for a year.
  • Approximately $5,440 for book donations, postage, Adobe InDesign, Confluence Wiki, and overhead/administrative costs.

Scott’s promise

Scott finished by saying that if you want to undertake a similar project, ask him. He will try to help.

This was a fun and inspiring talk. Thanks Scott!

Soon to be a Google technical writer

I have a bit of news to share:  I’m joining Google and saying farewell to Atlassian.

So long Atlassian, and thanks!

Friday 5 July was my last day at Atlassian. It was awesome being part of the Atlassian phenomenon for six years. A huge thank you to all Atlassians, and everyone in the wider Atlassian community: customers, add-on developers, experts, technical communicators and doc sprinters around the world! You’ve given me such great opportunities, and made me push myself into trying things that challenged me personally. (If someone had said six years ago that they’d spotted me doing any form of public speaking, my somewhat hysterical reply would have been, “Ha ha ha, nope, that’s some other Sarah.”)

Hallo Google

It’s time to go adventuring again. In a couple of weeks’ time, I’ll be a technical writer in the Developer Relations team at Google Sydney. This is tremendously exciting, and just a bit scary. That’s the best way to feel when starting something new.

Stepping into the sky

Stepping into the sky

I took this photo on a recent walk in the bush after a heavy rain storm. It’s a puddle reflecting the trees and sky.

How to write effective blog posts

Our technical writing team at Atlassian has just started presenting a series of workshops for other Atlassians, on how to write effectively. This post contains the material for a workshop that focuses on writing blog posts. I’d love any feedback you may have.

In an earlier post about the workshops, I wrote how enjoyable and rewarding it is for us, as technical writers, to present these workshops. That post also contains the material for the first workshop, which focuses on writing effective “how to” guides, and describes the format of the workshops.

Now let’s take a look at the workshop material on effective blogging.

Getting started on your blog post

How do you write a blog post?
One word at a time… not!

The big picture is the important thing.

  • Sit back, think, and plan the post before you start.
  • While writing, if the words don’t come, make a note and continue writing. Preserve the big picture. Come back later to fill in the gaps.

A philosophy of blogging

Choose your style, then grab your reader:

  • Maintain a character in your blog, so that people can start seeing you as a friend. Be yourself. (More about the social side later on.)
  • Consider your tone. If you’re writing on a corporate blog, read the guidelines on corporate voice, tone and style.
  • Write each post around a story or a ‘hook’. This will give the post a theme, making it easier for you to write and easier for people to read. (More about telling a story later on.)
  • Add structure to the content. Add headings. Split the information into easily-readable chunks. People want to skim and dip in. (More about structure later on.)
  • Tap into the power of social media. Link to other blogs and respond to comments. (More about the social side later on.)
  • Take advantage of your creative subconscious. Make notes, wherever you are. Writing is a creative process, and it keeps happening even when you think you’ve stopped! You’ll find yourself thinking of stuff to add to your document at odd times. While walking in the bush. Or in the middle of the night. Make a note. Email yourself. Put it on Remember The Milk. Whatever works. Such ideas are gems, and they’re at their freshest when you first think of them. Grab that freshness.

View every experience as fodder for your blog

Whenever something happens, think to yourself: “How does this fit into my blog?”

You can even write multiple blog posts as a result of a single experience or event. A while ago I wrote 4 posts resulting from one Atlassian ShipIt day (then called “FedEx days”), each post with a different theme:

  • A blog post on ffeathers, for people who are not Atlassians. This post introduces the concept of ShipIt (then called FedEx Day), tells the story of technical writers taking part in what is essentially a developer-focused activity, and shows lots of pictures.
  • An Atlassian ShipIt delivery note, describing the purpose and results of my ShipIt project. This is a more formal post. Everyone who takes part in ShipItis supposed to write one of these.
  • Another post on ffeathers, describing the software that I evaluated as part of the ShipIt project. This software, the SHO tool for guided help, is of interest to technical writers so it was useful to write it up separately.
  • A post on the Atlassian company blog, describing the new SDK (software development kit) that I used. This post is aimed at developers, showing them that the SDK makes it easy for even a technical writer to develop an add-on. There’s a fair bit of technical detail in the article. It’s also promotional, as suited to a company blog.

I could write another post about how to write 5 blog posts from one experience. (wink)

How to go about writing a blog post

[A useful practical guide.]

Step by step:

  1. Decide on your audience.
  2. Write the introduction.
  3. Write the title.
  4. Outline the post by creating the headings.
  5. Fill in the details. Keep each section short.
  6. If unsure, or struggling to find the right words, make a “TO DO” note and continue. Come back later.
    Hint: I use “xxxxxxxxxxxxxx” instead of “TO DO”. It’s quick to type, strangely satisfying, easy to search for, and stands out when I’m reviewing the page.
    [This bit often leads to some animated discussion amongst workshop participants. Some of them already do something similar. Others love the idea, and smile with delight.]
  7. Review the content yourself:
    • Have you included everything you intended to include?
    • Can you cut anything out?
    • Should you split the post into two?
    • Is your language and tone right for the audience?
  8. Ask someone else to review the page.
    As any writer will tell you, it’s impossible to review your own work. Your brain knows what you wanted to say, and that’s what your brain will see even if that’s not what’s written.

Talking to your audience

User icon: rrobins User icon: kegan User icon: jmlemieux User icon: brollins

Who do you want to read the post? Who are the people you’re writing for, and what do they already know?

  • Think about those people carefully. Make a mental picture of a person who has the characteristics of your target audience.
  • Use that imagined person to make all decisions about your post.
  • When in doubt about wording, speak to the imagined person out loud. Then write down what you said. Immediately.
  • If there’s more than one audience, consider writing a separate post for each audience. You could consider publishing the posts on different blogs.

Writing the introduction

Start the story right at the top. Tell people what the post is about and why you’re writing it. Hook the readers by letting them know you’re going to tell them a story.

Examples of a good introduction:

[At this point, the presenter opens each of the examples and talks the attendees through the salient points. We use the same articles to illustrate other points in the workshop later on.]

  • 5 Things I Learned When I Moved My Business to an Island
    “There are small towns. There are rural areas. And then there are islands. Islands that have no bridges, only ferries.
    Ferries that blow their horns on foggy days. That break down at the worst possible moment, usually when you have an important meeting with a new client. Ferries that will take you back home if you show up in line before the last one leaves the dock, at 7:30pm sharp….”
  • Social Media Fail: 5 Reasons I Will Unfollow You
    “The other day, I unfollowed someone on Twitter. At first glance, we appeared to have lots in common…”

Concocting a title

Make sure the title reflects the main story. This will attract readers and give you a good position in search results such as Google or Bing.

The title is your most important tool for helping people find your document. This is especially true on EAC, where people use the quick search a lot.

  • Put the key information at the beginning of the title.
  • Make the title describe the purpose of the document.
  • Be clever if you can

Example of a great title: Stash 2.4: Forking in the Enterprise

Telling a story

Write each post around a story or a ‘hook’. This will give the post a theme, making it easier for you to write and easier for people to read.

What is a story?

  • The simplest type of story is a use case.
  • Another good story is something that went wrong, and how you fixed it.
  • Or you could tell a funny story, provided it relates to the main content of the post.

Moving on to the main part of the post:

  • Describe your part in the story. Make it about you, or your team.
  • Then move quickly to the main topic.
  • Give plenty of factual information, preferably hard-won. That’s what people value. Code samples and screenshots are great.
  • Tell how the events changed you, changed the way you work, changed your product. That’s what a story is all about.

Examples of good story-telling:

Structuring a post

Add structure to the content. Yes, even in a blog post. People will skim and dip in. If they can’t do that, they’ll leave.

  • Split the content into easily-digestible chunks. Keep them short.
  • Use plenty of headings, so people can find the chunk they need. Research shows people’s eyes jump from heading to heading as they skim a page.

Example of good structure: 5 Things I Learned When I Moved My Business to an Island – notice the highlighted bullet points and easily-digestible sections.

Language and style

Keep it short and simple

Use simple words and short sentences.

Use active voice rather than passive

[Explain the difference between active and passive. Hold a bit of a discussion here. This is a difficult concept for many people.]

Examples:

  • Passive: The chocolate was eaten by the technical writer.
  • Active: The technical writer ate the chocolate.

Why use active voice? It’s shorter. And passive voice can be confusing, because sometimes it doesn’t say who must do what. Imperative (command) is even better, when appropriate.

Bad:

Your browser must be configured to xxx.
Reader thinks: OK, so I’ll assume someone has already done that for me when setting up my machine.

Good:

Configure your browser to xxx.
Reader thinks: OK, I’ll do that now.

Clarify technical terms and abbreviations

Explain important concepts at the top of the page.

Spell out each abbreviation the first time you use it on a page. For example:

If you’re using IE (Internet Explorer), ….

How to make sure people find your post

Let’s look at SEO (search engine optimisation). These are the key points for making sure people find your post:

  • Make the title meaningful, with important words near the beginning.
  • Make sure the URL contains real words.
    If you are blogging on Confluence, don’t use special characters like “?” in a page title, because the resulting URL will not contain words.
  • Decide the key words for your post. These are the key concepts, and the ones the people are likely to look for when searching.
  • Put your key words at the top of the post, in the introductory paragraph.
    This ties in well with our structure, where the first section contains a introduction and a summary of the story.
  • Put your key words in the headings in your post.

Making use of “social”

Blogging is a social activity. Tap into the power of social media:

  • Maintain a character in your blog, so that people can start seeing you as a friend.
  • Be yourself. Otherwise it’s difficult to maintain a consistent persona and people will soon pick it up if you don’t sound real.
  • Link to other people’s blogs. If your idea is an expansion of something someone else has written, include a mention of where you got the idea. If you’ve seen someone’s post about a related topic, link to it. The other bloggers appreciate this and will start linking back to you in return.
  • Be nice, positive and sincere. If you disagree with something, say so but be constructive. Some bloggers are successful by being horrid, but to make that work you have to be really good and have a curl on your forehead. I don’t like nastiness, manipulation or one-upmanship, so I wouldn’t recommend it.
  • Watch the post, and respond to comments. Build your audience, by showing them you care.
  • Find other blogs on a related topic, add comments there, and where relevant link back to your own post.

Resources

  • Kurt Vonnegut’s How to Write With Style.

    A great thing about Kurt’s guide is that it illustrates his principles so perfectly. This excerpt is from the section called “Sound like yourself”:

    …lucky indeed is the writer who has grown up in Ireland, for the English spoken there is so amusing and musical. I myself grew up in Indianapolis, where common speech sounds like a band saw cutting galvanized tin, and employs a vocabulary as unornamental as a monkey wrench.

    This bit is pretty cool too:

    Pity the readers

  • [Link to your corporate stylesheets and guidelines here too.]
  • Bloggers’ tips on blogging:
    • Seth’s post way back in 2006, a bit sparse on the “how to” but eminently elegant as always: How to write a blog post.
    • Seth’s post with more down-to-earth tips: Write like a blogger.
    • Neil Patel’s tips on engaging your readers in your blog: How to Write a Blog Post. Start reading from the top, then see what he has to say in the section titled “Hook your Readers”. It’s awesome.
    • My own, more personal account of blogging, from which some of the above material is drawn: How to write a blog post.

Workshops on effective writing – technical writers adding value

Our team at Atlassian has just started presenting a series of workshops for other Atlassians, on how to write effectively. People are very appreciative of the knowledge they gain in the workshops. In turn, we technical writers learn a lot from the participants. We see how much other people value our own skills. And we get a fresh look at writing and documentation, from another viewpoint. What’s more, the workshops are fun and invigorating. Added value all round!

I’m sharing the idea and content of the workshops in this post, because we’re finding them so valuable. It’s very rewarding as a technical writer, to see how much people value our knowledge and skill. It’s also interesting to see how much they appreciate a guiding hand in what we consider the very basics of writing a technical document.

Sometimes we forget just how much we know. :)

The format of the workshops

Each workshop takes the form of a one-hour session:

  • Introductions.
  • Lecture – see the material below. Questions are welcome at any time.
  • Questions and wrapping up.
  • Assignment of pages and posts for the workshop participants to work on at their leisure.

Before the session, the technical writer liaises with the manager of the team about to attend the workshop. We discuss the primary focus, and find out whether the team has any current plans to write documents or blog posts. Just recently in our organisation, a number of teams have put strategic initiatives in place to write and blog more. So our workshops come at a good time.

We also ask the participants and team leads to think of documents that need writing, so that their post-workshop assignments can be real documents.

After the session, the participants complete their assignments and choose one of the available technical writers to do a review. The review is a half-hour one-on-one chat, focusing on the document and any further questions the participant may have.

Kicking off the workshop

[The next few sections in this post contain the content of the workshops. The content is on a page on our internal wiki, which the technical writers use as a basis for the workshop. Participants can also use the page as a reference after the session.]

In this session you’ll learn how to write documents that people will find, read, and get what they need from. The aim is to provide a practical guide to help you get started quickly, and to put you in touch with the technical writers who can assist with reviewing your work.

We cover two types of document:

  • A “how to” guide on the corporate intranet.
  • A blog post on the corporate external blog.

Getting started on a document

How do you write a document?
One word at a time… not!

The big picture is the important thing.

  • Sit back, think, and plan the document before you start.
  • While writing, if the words don’t come, make a note and continue writing. Preserve the big picture. Come back later to fill in the gaps.

Talking to your audience

User icon: rrobins User icon: kegan User icon: jmlemieux User icon: brollins

Who do you want to read the document? Who are the people you’re writing for, and what do they already know?

  • Think about those people carefully. Make a mental picture of a person who has the characteristics of your target audience.
  • Use that imagined person to make all decisions about your document.
  • When in doubt about wording, speak to the imagined person out loud. Write down what you said. Write it down immediately, while it’s fresh. [I usually tell an anecdote here, about how some writers stick a picture of a person on their computer monitor, and talk to that picture.]
  • If there’s more than one audience, consider writing a separate document for each audience. For example, consider separate documents for administrators and ordinary users.

The structure of a page

[The aim of this diagram is to illustrate that a page should have a number of headings, with short bits of text between them. After a quick look at the diagram, we discuss the sections in more detail below.]

Structure of a page

Structure of a page

State the purpose and audience at the top

Tell people who the document is for, and what it will help them do. This will let them know if it’s the right document for them.

Separate the concepts (“what” and “why”) from the task (“how”)

Some people already know the concepts. They’ll skip past that bit and go straight to the “how”. Other people know how to do something – they’ve found the right spot in the user interface, or found the right form on the intranet. But they want to know why they should do it, or what it means.

Use “chunking”

Split the content into easily-digestible chunks. Keep them short.

Use plenty of headings, so people can find the chunk they need. Research shows people’s eyes jump from heading to heading as they skim a page.

Lead your reader by the hand

Give clear, numbered steps. Don’t skip any steps.

People have come here because they’re stuck. Don’t worry, they’ll go away again as soon as they’ve got the idea.

Add related topics and/or next steps

Send the readers away immediately if they’re in the wrong place. After that, don’t send them away until you’re sure they’ve got what they need. So, keep links to a minimum in the main portion of the page.

  • At the top: In the section about purpose, add links to documents the reader may need instead of this one. For example, if you have separate documents for administrators and users, link from the one to the other.
  • At the end: Put related topics and next steps at the end, when you’ve finished with your reader.

Examples from our product documentation

[At this point, the workshop participants have already absorbed a lot of theory. It's a good time to show them some examples of good and bad design. Use these examples as a discussion point. Ask the participants what is good or bad about each page.]

Good structure

https://confluence.atlassian.com/display/DOC/Deleting+or+Deactivating+Users

Good structure and design

Good structure and design

Comments:

  • Our current style is to put the related topics at the top on the right, instead of at the bottom. We’re discussing a change, because the design doesn’t work too well on mobile devices.
  • Instead of a warning macro, we’ve used a panel (uncoloured) with an exclamation icon. There’s some discussion about coloured panels, and whether people skip over them when reading a page. See the references to “banner blindness” in the resources section below.
  • [This is a good place to break for a quick chat about banner blindness. Find out what the workshop participants think about it, and how they themselves read a document.]

Not-so-good structure

[This is a page that has grown organically, with contributions from many people over a long period of time. It's had a revamp in the latest version of our documentation. The link points to an earlier version.]

https://confluence.atlassian.com/display/CONF50/Database+Setup+for+Oracle

Unplanned structure and design

Unplanned structure and design

Comments:

  • No clear step-by-step flow.
  • No indication of what each section is for, and whether you need to do them all.
  • Other comments? [This is a good place for discussion amongst the workshop participants.]

Language and style

[This section contains a few key tips on language and style - the bread and butter of technical writers, but not necessarily well known by other people.]

Keep it short and simple

Use simple words and short sentences.

Use active voice rather than passive

[Explain the difference between active and passive. Hold a bit of a discussion here. This is a difficult concept for many people.]

Examples:

  • Passive: The chocolate was eaten by the technical writer.
  • Active: The technical writer ate the chocolate.

Why use active voice? It’s shorter. And passive voice can be confusing, because sometimes it doesn’t say who must do what. Imperative (command) is even better, when appropriate.

Bad:

“Your browser must be configured to xxx.”
Reader thinks: OK, so I’ll assume someone has already done that for me when setting up my machine.

Good:

“Configure your browser to xxx.”
Reader thinks: OK, I’ll do that now.

Clarify technical terms and abbreviations

Explain important concepts at the top of the page.

Spell out each abbreviation the first time you use it on a page. For example:

If you’re using IE (Internet Explorer), ….

…with regard to Workplace, Health and Safety (WHS).

Titles

The title is your most important tool for helping people find your document. This is especially true on a Confluence wiki, where people use the quick search a lot. The quick search is based entirely on the page title.

  • Put the key information at the beginning of the title.
  • Make the title describe the purpose of the document.

How to go about writing a page

[After quite a bit of conceptual and theoretical information, the workshop participants welcome a practical guide at this point.]

Step by step:

  1. Decide on your audience.
  2. Write the purpose.
    First write it for yourself, then refine it for the audience. This helps to form the content of the page.
  3. Write the title.
  4. Outline the document by creating the headings.
  5. Fill in the details.
    Keep each section short.
  6. If unsure, or struggling to find the right words, make a “TO DO” note and continue. Come back later.
    Hint: I use “xxxxxxxxxxxxxx” instead of “TO DO”. It’s quick to type, strangely satisfying, easy to search for, and stands out when I’m reviewing the page. [This bit often leads to some animated discussion amongst workshop participants. Some of them already do something similar. Others love the idea, and smile with delight.]
  7. Review the content yourself:
    • Have you included everything you intended to include?
    • Can you cut anything out?
    • Should you split the document?
    • Is your language and tone right for the audience?
  8. Ask someone else to review the page.
    As any writer will tell you, it’s impossible to review your own work. Your brain knows what you wanted to say, and that’s what your brain will see even if that’s not what’s written.
  9. If possible, do some user testing.
    Grab a colleague from a different department. Get a different perspective!
  10. Watch the page, and update it based on comments.

More about structure, at space level (specifically for Confluence wiki)

[It's time for more theory.]

We’ve already talked about the structure of page. The structure of your space also important. People often need to browse to see what’s available. Perhaps they don’t know what to search for, but they do know the general area they’re in.

Scenario: Jack searches for “proxy” and finds a page. But it’s not the one he wants. So he looks at the nearby pages.

How:

  • Group related topics under a common parent.
  • Use the Documentation theme to show the space structure.

Making sure people find your page

Already discussed:

  • Structure of a wiki space
  • Page titles
  • Links to related topics

In addition to the above, let’s look at SEO (search engine optimisation) both internal (on the intranet, for the Confluence search engine) and external (on the corporate blog, for Google etc).

These are the key points for making sure people find your page or post:

  • Make the title meaningful, with important words near the beginning.
  • Make sure the URL contains real words.
    If you are blogging on Confluence, don’t use special characters like “?” in a page title, because the resulting URL will not contain words.
  • Decide the key words for your post. These are the key concepts, and the ones the people are likely to look for when searching.
  • Put your key words at the top of the post, in the introductory paragraph.
    This ties in well with our structure, where the first section contains a introduction and a summary of the story.
  • Put your key words in the headings in your post.

Tools

  • Templates and blueprints – make some of your own.
  • Use the spell checker in the browser.
  • Gliffy is great for simple diagrams.

Other hints

  • Writing is a creative process, and it keeps happening even when you think you’ve stopped!
    You’ll find yourself thinking of stuff to add to your document at odd times. While walking in the bush. Or in the middle of the night. Make a note. Email yourself. Put it on Remember The Milk. Whatever works. Such ideas are gems. Don’t lose them.
  • Optimise your page for people using mobile.
    No section and column macros (on Confluence wiki).
    Short sections with lots of headings.
  • Limit the number of note- and warning-boxes to a maximum of two per page. Using more than this can indicate an organisational problem in the text.

Writing blog posts

[This is just a summary. We have another workshop that focuses on blog posts.]

Your blog post is likely to be technical, so the process of writing it has much in common with writing a technical document.

Here are some quick pointers:

  • Maintain a character in your blog, so that people can start seeing it as a friend. Blogging is a social activity. Be yourself! Otherwise it’s difficult to maintain a consistent persona and people will soon pick it up if you don’t sound real.
  • If you’re writing on the corporate blog, ask for guidelines about the tone and style to use.
  • Write each post around a story or a ‘hook’. This will give the post a theme, making it easier for you to write and easier for people to read.
  • Make sure the title reflects the main story. This will attract readers and give you a good position in search results such as Google or Bing.
  • Add structure to the content. Yes, even in a blog post. Put headings in the post itself. Split the information into easily-readable chunks.
  • Give plenty of factual information, preferably hard-won. That’s what people value. Code samples and screenshots are great.
  • Link to other people’s blogs. If your idea is an expansion of something someone else has written, include a mention of where you got the idea. If you’ve seen someone’s post about a related topic, link to it. The other bloggers appreciate this and will start linking back to you in return.
  • Be nice, positive and sincere. If you disagree with something, say so but be constructive. Some bloggers are successful by being horrid, but to make that work you have to be really good and have a curl on your forehead. I don’t like nastiness, manipulation or one-upmanship, so I wouldn’t recommend it.

Resources

  • Kurt Vonnegut:

    Here’s my all-time favourite: Kurt Vonnegut’s How to Write With Style.

    The best thing about Kurt’s guide is that it illustrates his principles so perfectly. This excerpt is from the section called “Sound like yourself”:

    …lucky indeed is the writer who has grown up in Ireland, for the English spoken there is so amusing and musical. I myself grew up in Indianapolis, where common speech sounds like a band saw cutting galvanized tin, and employs a vocabulary as unornamental as a monkey wrench.

    This bit is pretty cool too:

    Pity the readers

  • Avoiding framed and decorated text boxes:
  • [Link to your corporate style guide here.]

That’s the end

In designing the content of the workshop, my aim was to give the participants as much practical guidance as possible in a short space of time. I picked the top things we technical writers know, about how to make a document work.

To add variety to the one-hour session, I chose a mix of theory and discussion sections. The sessions to date have been lively and interactive. We ask participants to complete a feedback form a week or so after each session.

The actual writing happens after the session, in the participants’ own time. They can then request a one-on-one review with a technical writer, before publishing their document either internally or for the whole wide world. Participants have expressed their thanks and said the content is useful, and have indicated a wish to attend a follow-up session.

What do you think of this type of workshop, and its potential as a way technical writers can add even more value to our organisations that we already do? I’d love to hear if you have run something similar within your own organisation too.

Follow

Get every new post delivered to your Inbox.

Join 1,496 other followers

%d bloggers like this: