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.
How to go about writing a blog post
[A useful practical guide.]
Step by step:
- Decide on your audience.
- Write the introduction.
- Write the title.
- Outline the post by creating the headings.
- Fill in the details. Keep each section short.
- 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.]
- 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?
- 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
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:
- 5 Things I Learned When I Moved My Business to an Island – Engaging and effective.
- 21 Things You Need to Know About Self-Publishing 2.0 – Great start, and nicely-rounded story followed by the 21 points. Tends to ramble towards the end.
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.]
- 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.
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.
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.
- 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.
Scott Nesbitt has asked a number of technical writers, and I’m one of the privileged, if we’d like to write a guest post on the DMN Communications blog. So I did: What makes a technical writer tick?
Writing for someone else’s blog is fun! It’s also interesting.
You suddenly have all sorts of new considerations. You don’t know exactly when your post will be published. Potentially, you don’t know your audience as well as when writing on your own blog. You’re not sure how much editing the blog owner will do on your post after you’ve submitted it. You don’t have hands-on control of the formatting and you can’t make final tweaks just before publication.
Publication date arrives
I waited with bated breath. Seeing my post appear: Fun — almost as if reading it for first time. Surprise — the format is unfamiliar. Even though I’ve visited DMN Communications often before, it was still odd to see my words up there in that format. When writing on your own blog, you write in a WYSIWYG editor. You craft the appearance along with the words.
Hmmm. That’s the way most of us operate in our day jobs too. This made me think again about the trend towards content reuse and single sourcing, such as via DITA, where you need to write format-agnostic content. It’s difficult!
From the point of view of the blog host
On the subject of inviting guests to blog on your site, Scott has written some interesting notes from his perspective.
Scott added some headings into my post. That was a good editorial decision. He also let me know that he had done it before he published the post. He added the image at the top, and then added my fish image at the bottom when I emailed it to him later. Awesome to-ing and fro-ing. Scott also let me know how much extra traffic my post had generated. That was cool. Thanks Scott!
Comments from readers
I’m thoroughly enjoying the comments other technical writers are leaving on the post. Who can resist the “fish called Rhonda“? Bring on the puns, guys and gals! And if you want to add more serious stuff, well, that’s OK too 😉
Technical writers are simply the best. Better than all the rest. With another bow to Douglas Adams: It is a bizarrely improbable coincidence that anything so mind-bogglingly useful could have evolved purely by chance.