Sarah Maddox's Blog, page 28

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

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. [image error]

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

[image error] [image error] [image error] [image error]

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.]

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.

Invitation to a webinar about doc sprints tomorrow

Along with the Society for Technical Communication (STC) I’ll be presenting a webinar tomorrow, about doc sprints. It would be great if you can join us!

The webinar is titled Doc Sprints: The Ultimate in Collaborative Document Development. It’s full of information about planning and running a doc sprint, and how doc sprints are useful in developing the documentation our readers need.

As well as information gleaned when running doc sprints at Atlassian, I’ve included stories and tips from doc sprinters around the world: Anne Gentle, Swapnil Ogale, Ellis Pratt, Katya Stepalina, Andreas Spall, Jay Meissner, and Peter Lubbers. The stories are what make a good doc sprint awesome.

How to sign up for the webinar

Dates, times, and registration details are on the STC site: Doc Sprints: The Ultimate in Collaborative Doc Development.

Oh, just so you know, it will be 6am here in Sydney. I’ll watch the sun come up while presenting the session.

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

[image error] [image error] [image error] [image error]

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

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

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

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:

Decide on your audience.
Write the purpose.

First write it for yourself, then refine it for the audience. This helps to form the content of the page.
Write the title.
Outline the document 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 document?
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.
If possible, do some user testing.

Grab a colleague from a different department. Get a different perspective!
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:

Banner blindness
Fancy formatting ignored – looks like an ad


[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.

Banner blindness and technical documentation

We had an interesting discussion in our team at Atlassian this week, about framed, decorated boxes containing tips, warnings and notes. Should we use them? I’d seen some user testing results that suggest people don’t read content in such boxes. Another writer pointed out that the tests didn’t focus on technical documentation specifically, and that people may expect and therefore take notice of  framed notes in technical documentation.

The research is by Jakob Nielsen, a well-known designer of user interfaces:

Banner Blindness
Fancy Formatting, Fancy Words = Looks Like a Promotion = Ignored

I found both articles enlightening, with their focus on tracking the eye movements of the test subjects. In particular, the videos are worth watching.

How to highlight notes if not in boxes?

User testing shows that people skim a page by jumping from heading to heading. One way to bring notes to their attention is therefore to have a “Notes” heading, followed by bullet-pointed notes.

If a note contains more than a sentence or two, it’s probably worthy of its own heading and short section.

What about speech bubbles?

Anne Gentle wrote about drawing speech bubbles in your documentation, to bring particular items to a reader’s attention. She’s using CSS to draw the bubbles. Very cool! Anne’s post led me to wonder if people are more likely to read content that’s in speech bubbles rather than rectangular boxes. Perhaps we’re conditioned to notice speech bubbles, and to think of them as likely to contain information that’s relevant and easily consumable.

What do you think?

This is such an interesting topic! I’d love to know the thoughts of other technical writers and of people who read documentation. Do you tend to ignore words enclosed in boxes? Have you done or seen any user testing that indicates whether people unconsciously skip over notes in framed, decorated boxes? Can we “train” our readers to read such blocks of content, by consistently using the same format for notes and warnings? But then, what if our documentation is web-based and so every page is page one, as Mark Baker so eloquently puts it – will the reader who comes surfing in off the ad-riddled web be conditioned to ignore text in boxes?

How to manage attachment usage in Confluence wiki with some Python scripts

Do you need to find out whether the attachments on a Confluence wiki page are used anywhere in the space? Having discovered they’re not, do you want to delete them from the page? I’m hoping this post will help.

The Confluence user interface doesn’t offer the option to delete attachments in bulk. Nor does it offer any way of cross-referencing attachment usage. You can’t get a list of attachments and find out where they’re used. So, I’ve written four Python scripts that you can run consecutively to do the following:

Get a list of all attachments on a given page.
Get the content of all pages in a given space.
Produce two reports, one listing the attachments that are not referenced anywhere in the space, and the second showing the attachments that are referenced and the pages that use them.
Accept a list of attachment names and delete them from a given page.

Our use case

In the Confluence documentation we have a page called Space Attachments Directory. It’s been there for yonks. It has an enormous number of screenshots attached to it (396, to be precise). The page was created in 2005, with the aim of storing screenshots that can be re-used on various pages. A good aim in principle, but in practice unmanageable when applied across a large space maintained by many authors. Various technical writers over the years have either used or not used this page and its attachments.

As a result, we didn’t know how many of the attachments are actually used anywhere in the space. I suspected that only a few of the attachments were still in use.

Python to the rescue.

The scripts

The four Python scripts are available on Bitbucket. Please feel free to download and use them. If you have any suggestions for improvement, I’d love to hear them.

A friendly warning: These scripts are provided “as is” and without any guarantees. I developed them to solve a specific problem. I’m sharing them because I hope they will be useful to others too. If you have any improvements to share, please let me know.

1. getConfluencePageAttachments.py: Gets all attachments on a given Confluence page. It puts the list of attachments into a text file, and prints a report of the number of attachments and total file size.

2. getConfluencePageContent.py: Gets the content of all pages in a given Confluence space. It puts the content of each page into a separate text file, in a given directory. The content is in the form of the Confluence “storage format”, which is a type of XML consisting of HTML with Confluence-specific elements. A note for the curious: The “wherePageContent.py” script is a dummy, which simply tells you where to find getConfluencePageContent.py, which I wrote for a different purpose and which works well here too. (We need content re-use on Bitbucket!)

3. findAttachmentUsage.py: Reads a text file containing attachment file names, matches them against the source of Confluence pages, and produces a report on used and unused attachments.

4. deleteAttachments.py: Reads a text file containing attachment file names, accepts a Confluence page name, and removes the given attachments from the page.

Note: To run scripts 1, 2 and 4 successfully, you need access to Confluence, and the Confluence remote API must be enabled. Script 3 does all its work in text files. It’s like greased lightning. 

So, in my use case, how many of the attachments are actually used?
71

That’s right. Of the 396 attachments on the “space attachments directory” page, only 71 are still in use. The other 325 are taking up space on our documentation wiki, taking up space in our XML exports, and slowing down our processes when we copy the Confluence documentation to the OnDemand space.

What’s next?

After some final testing, I’ll run the scripts on our production wiki next week. The first candidate is the Space Attachments Directory page. We’ll look at other pages that have a large number of attachments too.

The findAttachmentUsage.py script produces a cross-referenced list of matched attachments and the pages that reference them. We may use that cross-reference to decide whether we want to retain the “space attachments directory”. We may decide instead to move all the attachments to the pages where they’re used, and remove the shared page.

How to run the Python scripts

New to Python? It’s fun, and remarkably easy. This earlier post describes how to download and use Python: Confluence full-text search using Python and grep. There’s more about Python, and some interesting comments from readers, on this post: Python as a useful tool for technical writers.

Python as a useful tool for technical writers

Every now and then, and perhaps particularly so when working on a wiki, we technical writers need to manipulate our content in some way that’s not provided by our content management system. A few times recently, I’ve dabbled with Python to solve some problems. Do you often find the need to wrangle your content outside your CMS, and do you use Python or another scripting tool?

Python is a scripting language. It’s easy to learn, especially if you’ve done some programming in other languages. It’s just the ticket for data manipulation. It also offers a number of useful libraries. For example:

There are various libraries that you can use to access a web application via a SOAP or an XML-RPC remote API. I use the “xmlrpc.client” library in a few scripts, to get access to Confluence data.
The “os” library is useful for creating directories on the local file system of the computer you’re running on. For example, I use it to create a directory for the script’s output file.
The “re” library offers regular expression functions.

A script to find duplicate page names across Confluence spaces

This was the first Python script that I wrote to wrangle Confluence data. I started with a specific problem: I had five text files, each containing a list of page names. These were the pages in five Confluence spaces, that we needed to copy into another, single space. The problem is that Confluence does not allow duplicate page names within a space. So I needed to check my lists for matching page names.

I hacked together a Python script that checked for duplicate page names. The script reads a text file containing Confluence space keys and page names, and reports on duplicate page names. My first script used nested lists to store and compare the page names. A kind Atlassian developer reviewed the script and suggested I use a dictionary instead. So I did. A dictionary stores data in key-value pairs. Much neater!

Then I thought: Some people may not have their page names in a handy text file. They may want to get a list of all pages in a Confluence space. So I wrote a script to get the names of all pages in a given set of Confluence spaces.

The details of the scripts are in this post: .

A script to get the source code of all pages in a Confluence space, for a full-text search

The search functionality in the Confluence web interface will return results from the visible content of the page, but it cannot get inside the XML-like elements that make up the Confluence storage format. For example, it’s not possible to find all pages that reference a certain image. And you can’t search for macro parameter values. This means, for example, you can’t search for all pages that include content from a given page.

Just recently I wrote a script that gets the XML storage format of all pages in a given Confluence space, and puts the code into text files on your local machine. Then you can use a powerful full-text search like grep, to find what you need. The details are in this post: Confluence full-text search using Python and grep

More on the way

I’m currently writing a couple more Python scripts to solve another problem. I’ll blog about it when I’ve finished.

Resources

If you’re interesting in Python, here are some links you many find useful:

Python documentation
The Python Tutorial
Python libraries

A chuckle, courtesy of the Python technical writers

From the Python documentation:

By the way, the language is named after the BBC show “Monty Python’s Flying Circus” and has nothing to do with reptiles. Making references to Monty Python skits in documentation is not only allowed, it is encouraged!

Probably not a python

Last week I was lucky enough to be in New Orleans in the USA. I went on a tour of the Honey Island swamp, and saw this snake coiled comfortably on a tree trunk. I’m not sure what type of snake it is. Maybe a Copperhead:

What do you use?

Do you often use Python or some other scripting tool to automate those pesky tasks your CMS can’t handle?

STC Summit 2013 wrapup #stc13

Today is the last day of  STC Summit 2013, the annual conference of the Society for Technical Communication. All the sessions are finished, and I’m wrapping up my blogging before getting on a plane. You’ll find my posts under the tag stc13 on this blog.

Kudos and a big vote of thanks to Paul Mueller, Chris Hester and the STC conference committee for organising such a great event. From my point of view, the organisation was flawless. I had fun, learned a lot, met great people, and spoke my piece to my satisfaction too. All of those are thanks to the hard work of the organisers.

There were 80+ education sessions, spread over 7 tracks, as well as various workshops, demos, trade expositions, training sessions and social events. I’ve blogged about the sessions I attended. Please take the posting dates with a pinch of salt. My WordPress site is set to Australian time.

Data visualisation
A marketing communications career
Engaging infographics
Doc sprints (this is the session I presented)
Conveying messages with graphs3
Creating user experience for gamified products
From technical writer to content strategist
Documentation teams and company mergers
Flexible content and future-ready organisations
Information development flexibility in Agile
EPUB and technical communication at STC Summit 2013

Because there were many sessions running concurrently, it’s not possible to attend them all. I also attended a progression (a sequence of short talks within the space of an hour) where the pace was too fast for me to take notes.

More sources of information

Kai Weber has published some posts about the conference. Knowing him, he’ll come up with more once he’s made the long trip back to Germany. See posts tagged “stc13″ on Kai’s blog.

Twitter is very active at the moment. You can catch the tweets on the #stc hash tag. That feed will fade in a few days, when the Twitter search API times the entries out.

You’ll find a full list of sessions, along with information about the speakers and related links for each session, at the STC Summit 2013 site on Lanyrd.com.

I’m sure the STC will publish a summary and more links soon. And there are other bloggers around too. Stay tuned!

Pictures

At the opening session and keynote presentation on Sunday. The stage before the action starts:

The audience getting ready for the big event:

The keynote speaker was David Pogue, technology columnist for the New York Times and creator of the Missing Manuals series. At this Summit, David was awarded honorary membership of the STC. Here’s Alan Houser, outgoing STC president, with David Pogue:

David in full swing:

Intrepid ghost hunters on the Atlanta Ghost Tour:

Nope, not really convinced there’s a ghost around here, but we’re having fun anyway:

Thanks again everyone at stc13!

Data visualisation at STC Summit 2013

This week I’m attending STC Summit 2013, the annual conference of the Society for Technical Communication. I’ll blog about the sessions I attend, and give you some links to other news I hear about too. You’ll find my posts under the tag stc13 on this blog.

This is the last session of the conference! It’s called Data Visualization: Seeing through the Numbers, presented by Phylise Banner. Phylise will also present some material from Rob Mitchell.

The most important map in the world

Phylise showed us a map of the Soho area of London. For the work we do as technical communicators, this is the most important map in the world.

John Snow, who lived in England in the 1800s. During the great cholera outbreak, he plotted the homes of the people who were dying. From this map, he was able to trace the source of the disease to the water source. The notion of relational data telling a story. As a result, the city owners took the handle off the Broad Street pump, and the outbreak stopped.

Ten questions we need to ask

What story are you trying to tell?
What actions do you expect people to take? Are you creating visualisations for a decision maker, an explorer, or whatever, and what actions will they take based on your data?
What route will you take? Explore the data further. There are places where you can get data and explore it. Until you see what is there, you don’t know what you’re looking for.
What is the difference between qualitative and quantitative data? You need to know the difference. Quantitative is numbers and values. Qualitative is descriptive data. Some data is both.
Where does the data come from and what are the sources? Site your sources, and link to it if you want. Make sure it’s real, secure and correct. This may not be an easy task. Think about where else you can get it from.
What tools are available? There are some really interesting and good tools available:

ManyEyes, from IBM. This is an online open tool, one of the best out there. Explore the data sets available here, as well as the visualisations. Be aware, if you put your data up here it will be visible to the world. Playing with this tool is a great way of learning. Read the section on data format and style.
Tableau Public is a free version of Tableau. A great free tool.


What are the best practices? Best practices for working with data are different from those for working with visualisations. It’s not about being a mathematician or statistician, but it is about getting to know the field.

Read Stephen Few and Tufte.
Avoid pie charts. (This has come up in all three of the data visualisation sessions I’ve attended at this conference.)


What to do with the data?

As an exercise, try comparing and contrasting the nutrition facts from difference restaurants. Phylise showed us three PDF files from various restaurants. How can you process a PDF file? You could try an OCR. But the first step is to decide the story you want to tell, then extract the relevant data. Type it into Excel so you can work with it.
Phylise showed us an Excel file where a single column contained 1 to 3 values, and occasionally text. This is the kind of mess you often get. So, you’ll need to clean the data before you can use it. This often takes up a large part of the task.


Learn regular expressions and Excel’s find/replace syntax, including wild cards. See Regular-Expressions.info.
Code dichotomous variables to 1 and 0.
Pay attention to case. In qualitative data, a difference in case is a different variable.
Watch for invisible baddies! For example, spaces at the beginning and end of column. This expression is your friend: ltrim(rtrim(Field))
Watch out for ampersands. Use the word “and” instead.
Remember that 1.0 is not the same as 1. Check your character types,and watch your floats versus integers. When rounding, make sure you have a standard policy.
Watch for outliers – data points that don’t fit in with the data. You can decide to take these out, if they’re not important to your data. But think about what it means. The outlier may be what tells your story.
Beware of the acceptable leading zero. For example, there are zip codes that begin with zero. Make sure the data type is text, if relevant.
If you’re using comma-separated values, use quotes. Otherwise you’ll run into trouble when the data itself contains commas.
Write macros to clean your data, if you get the same data regularly. This is where technical communicators have the skill sets required.


Figure out what the data is saying. For example, in qualitative data, you may need to know how many times certain words come up.
Decide on the best way of representing the data. For example, to create a word cloud, you may need a document containing all the words, repeated the relevant number of times. Phylise showed us a case where it took her more than a week to clean the data, then 30 seconds to generate the word cloud.


What is the context? What is around the data, and what do you want to say in the specific environment?
What comes next? What other stories can you tell, and what new data can come from the data you have. You’ll never know this until you know the context of the data you have.

Some data to play with

Phylise shows us a list of data sources. They will be available on SlideShare. Here are a few I had time to note down:

http://www.google.com.au/publicdata/directory
http://www.data.gov/
http://www.faa.gov/about/office_org/headquarters_offices/apl/aviation_forecasts/

Tools

Some I noted:

http://www.visualthesaurus.com/
Mindmapping
Timelining

In summary

There’s data behind every visualisation. Unless you get to know the data, you’re just creating another picture. You can become incredibly valuable if you go for what it means to work with the data.

ManyEyes is a wonderful way to start.

A marketing communications career at STC Summit 2013

This week I’m attending STC Summit 2013, the annual conference of the Society for Technical Communication. I’ll blog about the sessions I attend, and give you some links to other news I hear about too. You’ll find my posts under the tag stc13 on this blog.

I’m attending a session titled A Marketing Communications Career: Making the Transition. The presenters are Barbara Giammona, Vici Koster-Lenhardt, Rich Maggiani, and Eric Koup.

Summary of how marketing looks from the tech comm side

How does a technical writer move into marketing? Someone comes and asks you to write content for the website, or a proposal, or a document to solve a crisis.

Some technical writers aren’t comfortable with writing marketing content. We’re comfortable writing something we can touch and test.

Another way to come into marketing: Perhaps your manager offers to change your title to be tech writer / marketing communication. Or you move fully into marketing.

What’s different about the role: The messaging, advertising, understanding the corporate and internal communications messaging.

For the rest of the session, the panel answered a number of pre-set questions. These are my notes from the resulting discussions. I haven’t tried to put people’s names next to each reply, but rather just summarised the whole picture.

Key differences in attitude

Typically, technical writers focus on details. They may struggle with structuring and presenting something from a different strategic point of view. The ability to evaluate what’s important is key.

The skills of a tech writer can come into play, being able to simplify the language into just what you need.

Is marketing lying? To many of us, it does seem so. So we should think about the transition path, if we want to move into marketing. Choose what’s closest to what we want to do.

The target market changes from users to buyers, and the content therefore becomes much more strategical. As soon as you start on the marketing path, you become more visible.

The requirements from management are not as clear-cut in marketing as in technical communication. You need to know the wider goals of the organisation. This requires less time in front of the screen and more time in trying to understand the aim. This takes collaboration.

Personality types

Looking at the Myers Briggs personality types, what is the difference between a tech writer and a marketing communicator?

A marketing person will have more contact with humans. Take this into account, especially if you are more of an introvert.

A marketing person tends to be intuitive, and are more of a feeling person than a thinking person. Perception is a strong gift for marketing. If you’re too rigid, the transition would be difficult.

Even if you’re a strong introvert, you can still play the extrovert, and make sure there are times in between when you can recharge. If you’re an extrovert, you may want to go into management.

Education

How would you go about taking the next step to getting into marketing?

You could be extreme, go back to school and get a degree, such as an MBA of marketing. Alternatively, do some certificate courses. Analyse your existing skills and see what more you need.

Volunteer for any project you can. If someone needs a newsletter, be the person who writes it.Newsletters may give you the opportunity to talk to higher management, and network with people you wouldn’t normally meet.

Look for volunteering opportunities outside the workplace too.

Set a clear goal of where you want your career to go. Then fill in the needs as you move along the path. Remember that your route to the goal may change along the way. Take it step by step.

Pros and cons, perks and challenges

Marketing is “way more fun” and “way cooler”!

Planning parties, making posters, organisational, project management… you’ll use all your skills. You’ll also work on more concurrent projects than you would as a tech writer. Emergencies happen, so you need to be fluid and juggle changes and concurrent projects.

It’s harder to plan vacation. Your work cycles are not based on the product release cycles.

You feel more part of the strategic plans of the company. You leap into a different track. You have a higher visibility to management. So you need to be sure you know what you’re doing.

Perks include travel. And you’ll make more money.

And you still get to write!

On the other hand, if you’re into tools, you’ll find that marketing is not about tools. It’s about communication rather than tools. Often the marketer asks someone else to do the design.

How do you break in?

The panel recommends the International Association of Business Communicators. They have the same kind of resources as STC, in terms of publications, knowledge banks, and job listings. They’re also very extrovert and welcoming.

Indeed.com is a job aggregator that will give you a feed of jobs available.

An organisation called Melcrum focuses on the employee and internal communication, useful if you’re in internal marketing.

Networking inside your own company will find you opportunities. Network outside your company too, as you never know where the opportunity will come from. Talk to your neighbour, volunteer organisations, and so on.

Do some volunteering inside your organisation. Managers don’t have time, and hate, to do the marketing for the projects they’re working on. Network with your sales force (customer care). Ask them if they need help, say “I can write that”. Take people to lunch. There is tons of marketing communication coming from HR. Find out who is writing the newsletter in your company. There may be a great opportunity to improve it.

Questions from the floor

These are the notes I took during the question-and-answer part of this session:

When talking to designers and other people who produce the deliverables, have a vision of what you want. You don’t need to know how to use the tools. You just need to know what you want.
What about recent college graduates looking to break into marketing communications? College doesn’t prepare you for some realities in the working world. One is the iterative nature – you do things again and again. The review process, and the number of stakeholders who have a say on your work, can also be a surprise. It’s very collaborative. Every day at work is a group project. If you’re just coming out of college, find a place that offers an internship. Many places offer great interships, and there’s a variety of them.

Thanks to the panel

This was a good insight into what marketers do, and some different types of marketing roles. Thanks Vici, Barbara, Rich and Eric.