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: How to find duplicate page names across Confluence spaces.

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?

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 graphs
• 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

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!

For a touch of light relief: A report from the intrepid band of STC ghost busters.

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!

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

1. What story are you trying to tell?
2. 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?
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.)
8. 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.
9. What is the context? What is around the data, and what do you want to say in the specific environment?
10. 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.

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.

Michael Opsteegh is about to present a session called Planning and Creating Engaging Infographics. I’m delighted to be here, having survived the Atlanta Ghost Tour last night and just two hours’ sleep.

Introduction

Michael started by discussing the graph on the front page of the Wall Street Journal this morning. Like most of us, he looked at the chart but didn’t read the article. So the only information he got was from the infographic on the side of the page.

Infographics are a powerful way of making information accessible and showing the relationships between pieces of information. You can weave a story consisting of graphs, images and more.

This presentation will focus mostly on the presentation of data, rather than the maths. The focus is on planning and building charts, graphs and larger infographics.

Examples of infographics

We saw a number of examples, and Michael talked us through the plus and minus points.

Infographics can be very persuasive, and can convey a lot of information.A graph, for example, is easier to digest and remember than a lot of text.

Sometimes they are overused. As a result, some people don’t like them. Still, they’re overall very popular.

Infographics can also be fun. Michael showed us one based on a batman theme.

There’s also a lot of room for misrepresentation.

Uses other than selling products and services

You could use an infographic for your resume. A website called visualize.me will produce an infographic based on your LinkedIn profile. But Michael recommends that you do the infographic yourself, rather than ending up with one based on a template.

There’s an infographic showing the wealth gap in America. It incorporates videos and charts, showing what people think the income difference is versus the actual situation. Unfortunately, it’s not easy to see who created the infographic. If someone isn’t prepared to acknowledge they created an infographic, then it may be difficult to trust it.

Skills required to create infographics

The creation of an infographic involves several disciplines. Michael has combined them into three areas:

• Liberal arts: Your infographic needs to tell a story, and it needs to be interesting. Companies are looking more and more to creative people to differentiate their products and services.
• Social sciences: You need some knowledge of human behaviour and cognitive sciences. How your infographic will be received and how to convey the information.
• Mathematics. You need to recognise if you’ve misrepresented your data, and understand the basics.

What about graphic design? If you have the skills, that’s great. Otherwise, hire someone to do the design. You give them the information and the specification for what the chart should look like.

Tools

You need to be able to record your thoughts and ideas, and also questions you have. Michael finds Evernote very useful, because he can jot down notes wherever he is. Evernote syncs the notes from his phone, tablet, PC. You can also include photos, links, videos.

Excel is ubiquitous and powerful. Use it to sort your data and produce preliminary graphs, to help see what your information will look like. Use pivot tables to sort and filter data. Michael demonstrated how you can drill down into data via pivot tables, then generate a graph.

Illustrator or PhotoShop are useful, if you are going to design your own infographic. Michael recommends Illustrator, because it’s great for vector tools and also includes a graph tool.

Visualising data

Bar charts, which can be vertical or horizontal. These are good for comparing figures side by side.

Pie charts are OK for representing data as a whole, and the different percentages within them. But research shows that people aren’t capable of seeing the distinctions well. A doughnut chart is just like a pie chart, with the centre missing. This is even less useful than a pie chart, because you lose the angles at the centre. Bar charts are usually better.

Scatter charts are good for finding patterns in the data.

Line graphs are a little like scatter charts, except that you’re dropping the points at regular intervals.

An area chart is basically a line graph filled in. Good for demonstrating changes over time. The Wall Street Journal chart this morning is an example.

Venn diagrams show relationships between discrete objects. The overlap shows the shared parts.

Flow charts (pedigree charts) show hierarchy or workflows.

Pictograms or iconographs show set numbers. Michael showed a page with a number of figures of people. Each figure might represent 1 million, for example.

There are many other types, like radial charts and maps. See the Wall Street Journal’s guide to designing infographics. Also the Napkin Sketch Workbook by Don Moyer.

Research

This is a critical stage. You need reliable and accurate data before you can move forward.

Identify your sources: must be current, reliable, non-biased.

Get permission to use the data. If a company conducted the research, for example.

Editing

This is where you decide what story you’re going to tell, and how you will tell it. Be aware, as you’re editing, that people will call you out if they find an anomaly or if they want to view it in a different way. So, play with different ways of viewing the data. See if there’s another way to tell your story.

Look for outliers in your data, and see how they affect the message.

What about rounding your numbers? Make sure you round at the end, after you’ve plotted the data. If you do it before, it will skew the graph.

If you’re going to place charts side by side, make sure you’re not comparing apples and pears. Make sure you’re using the right figures to illustrate a point. For bar charts, always start the axis at zero. For other graphs, if you need to start elsewhere make it very clear.

If you’re missing data, you may still be able to create the infographic. If you’re missing more than 2 points out of 10, then your infographic will not be reliable. Look at the data that’s missing and decide if it affects the perception of your story.

Plotting

This is the most fun part. The point where you actually draw the infographic.

Make sure you’re staying true to the data. Remain aware of the maths involved.

If you’re plotting several graphs for the same infographic, you’ll need to wireframe them. A wireframe is basically a set of boxes or circles (in Illustrator) to represent where the bits of data will go. The advantage is that you can move the sections around, before actually drawing them. Look at where the infographic will appear, to decide whether it needs to be tall and thin, or wide and short. Make sure your dimensions are correct.

Reviewing

Make sure your infographic visually represents the data that it ought to. Get a couple of colleagues to take a look and give you feedback. Ask them if there’s anything that worries them.

Ethical considerations

Throughout the process, make sure you don’t misrepresent the data.

Remember: Correlation is not causation. Michael showed us to line graphs that could show that ice cream consumption leads to murder.

Make sure the story you are trying to tell needs telling, and that it will benefit the audience.

Accessibility

There was a lively discussion around accessibility. Michael recommends you put a textual description on the page, near the infographic. An alternative is the new “longdesc” attribute. Don’t use the “alt” attribute, as it’s intended for a short description.

Thanks Michael

Thank you for an informative introduction to infographics. I’m keen to get my hands dirty creating one!

Today it was my turn to stand up on stage, knees quaking, watching people enter the room, and hoping what I had to say would be useful to them.

Overview

My presentation is called Doc Sprints: The Ultimate in Collaborative Document Development. It focuses on planning and running a doc sprint, and how doc sprints are useful in developing the documentation our readers need.

It also includes a number of stories and tips, gleaned from doc sprinters around the world. Thanks to Anne Gentle, Swapnil Ogale, Ellis Pratt, Katya Stepalina, Andreas Spall, Jay Meissner, and Peter Lubbers, for contributing their ideas!

What’s in the presentation

The presentation covers these topics:

• Introduction to doc sprints, agile environments, and why a doc sprint is a good fit for technical documentation.
• Who to invite, when to start, and how to ensure that the sprint will produce the documents you need.
• How to get the best out of the sprinters.
• Collaborative tools for use during the sprint.
• Sprinting across the world: Handling multiple time zones, early sprinters, late sprinters.
• How to run a retrospective, and why.
• Reviewing and publishing the documents, and writing up the results.
• Other innovative types of sprints for documentation teams.

Getting the slides

You can watch or download the slides from SlideShare:

Feedback from attendees

There were plenty of questions, both during and after the session, which is great. People came up and told me they enjoyed the presentation. That’s very very nice to hear.

There were also quite a few tweets during the session. This has to be my favourite, from Stephanie Donovan:

Stephanie’s tweet

If you see any blog posts or reviews appearing, let me know. And thanks so much to everyone for being such a great audience!

Early on Tuesday morning, Jean-luc Doumont presented a session titled Conveying Messages with Graphs. The blurb for this session is:

Graphical displays are still poorly mastered by technical communicators and other professionals. They seldom think of using graphs to communicate about data; when they do, they often use the wrong graphs or in the wrong way. Based on Doumont’s book Trees, Maps, and Theorems, about “effective communication for rational minds,” this session discusses how to select the right graph and how to optimize the graph’s construction, and how to phrase a useful caption.

Because this session is immediately before mine, I’ve decided not to take extensive notes. I’m too scatterbrained just before and just after live speaking! Instead, I’ll just give you my impressions from Jean-luc’s talk.

Jean-luc is an engaging and knowledgeable speaker, and the topic is very important in technical communication. I’m one of those text-oriented people. I find graphs difficult to interpret, and also difficult to create. A simple bar chart is good, but when you get to scatter-charts and 3D graphs, you leave me behind.

That’s why I attended Jean-luc’s session – to pump up my knowledge of conveying information in graphs. And I wasn’t disappointed. I’m now more comfortable with the more advanced types of graphs. More importantly, I know when to employ the simpler graphs, and how to knock out superfluous information. Simpler is better, as in most types of technical communication.

My two key take-aways are:

• Beware of the x-axis in Microsoft Excel. It assumes the data is string-based, even if you enter numerical values. If you want a true numerical reflection of your data, you need to set the data type explicitly.
• Horizontal bar charts are often more effective than vertical ones. The default is often vertical, but try flipping it around. A big advantage is avoiding vertically-oriented text.

Thanks Jean-luc for an informative presentation, delivered with charm. Here is a link to the handout from the session (PDF): Effective graphical displays.

Marta Rauch presented a session titled Game On! Creating User Experience for Gamified Products. Marta learned about gamification when she became interested in what motivates people to contribute to communities. This was around 2005. She is now a certified gamification designer.

A key take-away from Marta:

Gamification is already here. It’s time for us to get our game on!

Importance of gamification

Why should we pay attention to it, as technical writers? Gamification is the technique of applying game techniques in non-game situations, to motivate people and drive behaviour. So if that’s what we need for a particular piece of user assistance, gamification would be a good fit.

Game techniques:

• Game dynamics, which are rules to help you progress through the game
• Game mechanics that help you achieve your goals
• Game components that help you track your progress

Some stats

By 2014, over 705 of companies will have at least one gamified product. And by 2015, half will gamify innovation.

In the near future, a company that gamifies will be as important as eBay, Facebook, or Amazon.

In terms of money, the market is huge.

The focus is on engaging users. Gamification is the best way to engage younger workers (“millennial” workers). They have 10,0000 hours of gaming by age 21. This qualifies them as experts in gaming. They form 25% of the workforce now, and it’s a growing portion.

Marta highly recommends a TED talk by Dr Jane McGonigal: Gaming can make a better world.

Game changers for tech comm

The next 9 sections are about the things gamification is introducing that we need to consider in tech comm.

1. Understanding motivation

We need to understand our players’ (users’) motivation. What would engage them and what do they really like? To this end, Marta has set up special sessions at user conferences (such as Oracle OpenWorld) to talk about gamification. They had surprising results:

• Some players are not interested in badges, but rather in gaining access to information and people. That would be the kind of reward they would like.
• Some people really like to help other people. This can also be a reward.

There’s been a lot of research on the general types of players that play games, and what motivates them:

• Competing. Seeing how you rank against other players. Getting visibility.
• Completing tasks and checking them off.
• Helping other people.

In your gamified product, have tasks that play to these difference types of motivates.

Marta gave the example of the Nike fitness apps. They target main user groups, such as people who want to move through their fitness goals, or those who want to talk to and share with friends, or those who want to compete.

2. Gamified user assistance architecture and patterns

Plan the process, then keep the players motivated throughout.

There’s the concept of “onboarding” in games. It helps people know what to do when they get started. Games give you a plan to get started, and quests to follow or levels to conquer. Marta gave an example of a game used to teach maths.

A use case in tech comm: we may need to get people more involved in installing and configuring a product, and we want to keep them motivated all the way to the end.

In games, there’s often no documentation. Everything is embedded. There may be a quest to set up your user profile and get connected with other people. The game may also show you what other people are doing – a bit of peer pressure.

3. Gamification terminology

Marta listed some examples of game terms that have crept into general terminology, such as:

• Onboarding
• Avatar – this targets people who really like to customise and personalise
• Quests
• Leaderboards

4. Gamified messages

Messages are really crucial in a game.  They set the tone, as well as telling people what to do and giving them instructions. Think about a coach in real life. The messages are there just when they’re needed.

Often there is a link to the game FAQ. Inspired players love to share what they learn in a forum, and you may want to consolidate the top tips into the FAQ.

5. Writing style

The style is more informal, more friendly, intended to engage and motivate.

Marta pointed us to a chart by Amy Jo Kim – a social actions matrix. It shows the type of words you would use, depending on the quarter of the chart in which the target audience sits, or the type of quest.

6. Testing

When testing, have people sitting in a booth, unable to see each other. Watch how they’re doing. Are they achieving what we want them to achieve. Are they gaming the system in ways we don’t really want? Sometimes you may want to let them do that, and add it as a new feature, otherwise design it out.

7. Change mangement

If you’re going to upgrade or change the game, you must let the players know. They’ll be engaged and motivated, and will hate it if you take something away or change it while they’re in mid stream.

8. Accessibility

If your company is required to be accessible, your gamification must be too. The best information available is from game designers. See Includification as a good source.

9. Localisation

This is always a challenge, because you need to consider the culture as well as translation. Game strategies may need to change. In some countries, for example, you don’t want a leaderboard, because it’s not seen as a good thing to be at the top of the board. Or, it may be OK for a group instead of an individual to be at the top. There are also legal and privacy considerations.

Examples of user assistance

Marta picked a few examples that she thought would be fun to talk about, and to get us thinking.

• Microsoft Office – Ribbon Hero 2. “You’ve tried [various games]. Finally, here’s a game that will make you better at your job.” Marta recommends we download and try this game. It’s fun. Knights on horses, dragons. The “Canterburied Tale” quest helps you learn Word, for example. It has some excellent and fun animations. There are other quests to help you with Excel, and more.
• Adobe PhotoShop – Level Up. There are five key tasks. They had a business need to teach these tasks, to reduce support calls. An example is changing red-eye. The game takes you through various missions. You “level up” as you move through various missions, and its tied into social networks (Facebook). People love to share, so let them do it.
• Cisco – Mind Share. Cisco knows their players – these are certifications for network administrators. It’s really hard to get the certification, and was a painpoint for the administrators. Cisco knew that their administrators really enjoy SciFi games, so this was very successful for them.

A gamified reading app

This reading app was introduced in a gamification summit in San Francisco just a couple of weeks ago: “Read Social App”. You log in via Facebook, then start reading a book. The app shows your progress, and makes you feel good about it.

Marta showed us some great photos of how the app looks on a mobile device. You are presented with challenges to engage you in the content. Players type interesting tidbits they have learned while reading the chapter. The game also has ways to quiz you about what you’ve learned.

There’s also a way to unlock content. You can get access to a video, for example, as a reward for your effort.

You can see a tour at http://www.readsocialapp.com.

Gamification framework

How to get started:

• Define your business objectives
• Define your audience (players)
• Describe the behaviours you want them to follow
• Devise activity loops
• Remember it must be fun
• Deploy the tools you need

Marta’s responses to some questions

Gamification is not the same as games. It’s doing something with a business focus, but with a little more fun and a little more engagement.

Check your metrics. By gamifying a task, we aim to achieve that task a little more efficiently and effectively.

How does this apply to mid-career professionals? The data shows that the average age of a gamer is older than we thought. Also, a number of women play games. The Home Shopping network is very into gamification.

Thanks Marta

Marta finished off by pretending we (the audience) were on a gamification quest. Yaayyy, we’re already on stage 1, by attending Marta’s session. She took us through a number of “levels” we can follow,  to take us all the way to “mission accomplished” where we become gamification gurus.

Marta’s slide deck on SlideShare has a number of useful resources, for learning more about gamification. She also recommends a gamification course by Kevin Werbach, hosted on coursera. It’s pretty intensive, and you can gain an accreditation at the end.

This was a fun and inspiring session. It made me want to learn more. Thanks Marta!

Alan Porter‘s presentation is called From Technical Writer to Content Strategist. Here’s what Alan promises for this session:

Content strategy is a hot topic right now. The rise in corporate awareness of the value of content represents a great opportunity for technical writers to leverage their skills and experience. This session will help you position yourself to take advantage of that opportunity.

I’m looking forward to a talk by Alan, someone I admire for his diversity and depth of knowledge in the writing and communication fields.

Kicking off the session

After a couple of laughs about food, beer, and cut-and-paste (you had to be there!) Alan summarised the message of his session like this:

I’m going to talk about why I think technical communicators are best fitted to become content strategists.

Alan asked various members of the audience what their company does. After hearing a few specific answers (develop software, medical devices, etc) someone got the right answer: Every company is in business to make money. The other answers describe how we do it.

There’s no good developing something, without telling people about it. That’s marketing. Then you have to get people to buy it. That’s sales. Collect money. That’s finance.

And the fifth thing every company does is: Create content.

Different views of content

The thing about content is, it’s not seen as a strategic asset, because everyone creates is. We have to change this view. Depending on your role, you have a different view of content. Alan showed us some pictures of different ways of seeing a pig.

• Marketing puts the lipstick on the pig.
• The tech comm department shows a diagram of the pig and describes its various parts.
• The customer sees pigs wallowing in the mud.

What customers care about

They care about their problems, not ours.

We’re the people causing the disruptions.

As content strategists, we need to see the customer’s view of the content. And we, as technical communicators, are really good at that.

Definition of content strategy

One problem is that there are so many definitions of content strategy at the moment.

To Alan, it’s about:

Achieving business goals for us and our customers, by maximising the impact of content.

Analysing enterprise content

Companies don’t know:

• What content they have that is relevant to the customer.
• Where the content gaps are. The content is developed in silos, so things slip through the cracks.
• What resources are available elsewhere, either inside or outside the company, that you can use instead of developing new content.
• How to put processes in place for the more advanced aspects of content, such as retiring content, managing content.
• How to deliver content in the way the customer needs.

Where a content strategy fits

Alan showed us a four-part pyramid. From the top down:

• Editorial vision
• Content strategy
• New capabilities
• Foundational capabilities – these are the skills and knowledge that technical writers have. Things like metadata, for example.

Providing value to the customer

Content needs to be engaging, relevant and actionable. It must help the customer do something, so they can solve an immediate business need. Alan is currently analysing exactly what “engaging” means. In part, it must be something the customer wants to read, and can find easily.

Where’s the opportunity for a technical communicator?

A survey asked companies whether they have a unified content strategy that covers both marketing and multi-channel publishing. 80% of the responders said no.

That’s a big opportunity for us. But we need to change our terminology. Instead of talking about metadata and publishing processes, we must talk about business case and strategy. We need to use the vocabulary that the business uses. That’s the role of a content strategist.

Alan took us through a chart showing a typical framework for a content strategy process. The chart is in his slide deck on on SlideShare.

How to go about it

Be aware that content resides across the organisation. We need to break down silos, build bridges, talk to people, and get them to talk to each other. End the cold war between departments, such as tech comm, marketing, training, and so on.

Perform audits of your content. Find out what you have, across the organisation. This can be painful. You need people who understand content, and can ask questions about the business purpose of the content.

Offer advice, build a vision, and share that vision across the organisation.

Figure out a way your content adds revenue. Don’t say you can save money, because that will make it more difficult to get more budget the following year.

Thank you Alan

My key take away from this talk is that we must learn to talk the language the business people are talking, and use it to emphasize our skills, knowledge and impact. Thank you Alan for an encouraging glimpse into the life of a technical communicator become content strategist.

Kirsty Taylor’s presentation has an intriguing title: And Then There Was One … Documentation Team. Her team of technical communicators has recently undergone a company merger, and the documentation team has merged with another global team. Kirsty will tell us how to keep our sanity under such circumstances, while looking at the aspects of “culture, standards, time differences, and multiple Englishes”.

Setting the scene

Two years ago, the company Kirsty worked for was bought by a huge conglomerate. The conglomerate then acquired another company, and merged Kirsty’s documentation team with the teams in the other company. They now work together as one team. The company is in the business-to-business area, in the mining and defence industries.

The content team consists of 21 people, over 3 continents, and 11 offices. Kirsty manages the Asia-Pacific region, which covers 5 time zones. Kirsty’s team is also responsible for producing the classroom training materials for their consulting services.

In the last 5 years, there have been multiple acquisisions. The development and documentation team have been merged into one. It’s a distributed team, but with a central function and reporting structure.

This has involved aligning tools, standards, styles, responsibilities and roles. As technical writers come in from each organisation, they learn to use the standard tools. Their roles are aligned with the rest of the team.

One of the really strong things about the team is that they strive for consensus. There’s not always agreement, but there is consensus.

Mincom was added in 2010

This was the largest acquisition to date, in terms of merging of tech comm teams – there were 9 technical writers at Mincom. At first, the two R&D groups worked independently.

Technical writers are inherently curious people. So Kirsty and the other writers from both teams found each other and started talking and comparing notes. The structures and development team were still silos.

There have been many changes at top-management level too.

At the end of 2013, the R&D teams started working together. The technical writing team are still the teams who work most closely together. In March this ear, the VP of Quality Operations started, and the technical writers became part of the QO area.

Kirsty says that this was not like a takeover. It’s a much more collaborative environment, where they’re working together to decide how to move forward.

Refreshed branding

When the merger finally happened, the brand had to change. Luckily it was just the logo that needed to change. Not much else.

Standards committee

The team decided to form a standards committee for online help. There were too many writers to include everyone in the meetings, so they decided to involve the key team members with clever ideas.

Quick wins and collaboration

They looked at the things they could do to improve collaboration and get quick wins early.

• Style and standards for online help. This can be tricky, because everyone feels passionately. People had just recently redefined their styles, and didn’t want to change again. The approach was “not to kill anyone’s babies”. Don’t enforce the standards unnecessarily. Be grateful that we’re working together
• Output format. They focused on this because they’d be able to show stakeholders they were working together.
• The aim was to start looking like one company, in terms of the documentation, and to show they’re working together as a team, even if not a single team.
• Knowledge and experience gained from earlier mergers and acquisitions. It was incredibly useful having people who had already gained skills in negotiating decisions.

Problems and challenges

There are some problems to tackle.

Time zones. Kirsty has one person in Perth, while most of the team are in Atlanta. The time difference is 12 hours. There are 21 individuals in the team. Some like/need to start early. Others want/need to start late and work late. This makes team meetings difficult. One trick is to shuffle the meeting times, so that it’s not always the same people who have to work early or late.

The Australian team is used to having the team get together and make a decision, then go back to their desks and make the change. Now it takes adaptation to make the decisions monthly via a standards committee.

It’s tempting to group and name things for the former region or company. But this can create division. Management needs to guard against this. Instead, create a sense of unity and team. Use the words “our team” and “we” frequently and by default. Foster and develop relationships between team members across the pond. Buddy up the technical writers. Make sure they have the facilities (WebEx accounts, for example) to work together.

The company is still consolidating the tools to be used. For example, at first they used GoToMeeting. Then that was no longer available, and they’ve tried Telkom, WebEx, Skype. All have their problems. You need special headsets, or Skype credits, and so on. These ongoing changes can cause problems that can upset team members.

Other important tools are those for content creation, publishing, eLearning, etc. What is standard in one office is not necessarily standard globally. This can cause confusion.

There are changes to content style and writing standards. For example, do you use US or Australian spelling, syntax and punctuation? The information architecture needs to be consolidated. Think about the voice of your content, and more.

Encouraging the team to collaborate

Kirsty mentioned the idea of a team-building exercise somewhere half way between Atlanta and Brisbane. Hawaii, for example! But she laughed and said this probably wouldn’t happen.

Hold a global team meeting. Use games to help people get to know each other, and slide with a photo and short bio.

Have some internal social networking, in a tool like Chatter. Encourage team discussions, share articles and blog posts, ask questions, and respond when others ask questions. They do have SharePoint too, but felt that Chatter is more collaborative.

Pair people on projects, as “buddies”. Be flexible. Allow people to work from home for early or late starts.

Within SharePoint, try a shared team task list. This was a great initiative from the US team. A team task list is a request list from any team member who may need help from another team member. People can ask for a review, or help with something specific like CSS. This is also a useful tool for managers to see when team members need help, or someone is regularly giving help.

The team needs some way of sharing ideas. Hold virtual brown bag sessions, via webinars and recorded sessions.

Main themes

These are the main themes Kirsty has noticed so far:

• People. It’s all about change management and working on team relationships.
• Processes. When you’re aligning your processes, it’s a really good time to see why you’re doing something or not doing something. This can be really hard to justify.
• Collaboration. Focus always on co-operation and the fact that you’re one team.

Thanks Kirsty

This was an intriguing glimpse into the issues that arise when global teams are merged, and the creative solutions Kirsty and her team are putting in place. Thanks Kirsty!