News roundup

Here’s a summary of recent activities:

  • We have a client looking to engage a technical editor for a three month contract.
  • We have a client looking for an undergraduate (or recent graduate) to spend 6 to 8 weeks as a paid technical writer intern this summer.
  • We’ve a client looking for information on applying Net Promoter Score to user assistance documentation. If you’ve seen anything, please let us know.
  • Cherryleaf’s Ellis Pratt will be the guest speaker at June’s “Member Masterclass @ The IoD”. The topic is clever content creation in business. We’ll look at some of the most effective techniques for creating the types of content created in today’s business world. The event will be held at 6pm on 2nd of June 2015, at the Institute of Directors, 116 Pall Mall, London.

Atlassian no longer lets users comment on its documentation – good or bad news?

Last week, Atlassian sent out this message on Twitter:

This was a surprise, as Atlassian has been a strong advocate for having user comments appended to user documentation. Sarah Maddox, when she was working at Atlassian, posted the reasons why the company encouraged comments on her personal blog:

Continue reading

What is technical communication, actually?

As a technical communicator, sometimes it can be hard to explain to others what it is you do. In the olden days, it was simpler: you could say you wrote manuals. Then, in more recent times, you could say you wrote online Help and manuals.

Today, there can be uncertainty of what is and isn’t technical communication. It can be unclear if certain deliverables should be created by a technical communicator or by someone else. For example, if content moves from a Help page to an onboarding screen, is it still technical communication? If the text moves into the interface, should the technical communicator create it? Are walkthrough videos a function of training or technical communication?
Continue reading

A 2015 book list for Technical Communicators

Two years ago, we asked which books should Technical Authors read, and we received some great responses. It’s always worth revisiting this topic, so please let us know what we should add to this list:

  • Author Experience: Bridging the gap between people and technology in content management; Rick Yagodich
  • Best Practices for Technical Writers and Editors (IBM Press 3 book collection): DITA, Quality, and Style; Francis DeRespinis, Peter Hayward, Jana Jenkins, Amy Laird, Leslie McDonald and Eric Radzinski
  • Central Works in Technical Communication; Johndan Johnson-Eilola and Stuart Selber
  • Content Everywhere: Strategy and Structure for Future-Ready Content; Sara Wachter-Boettcher
  • Content Strategy for Mobile; Karen McGrane
  • Content Strategy for the Web; Kristina Halvorson and Melissa Rach
  • Conversation and Community; Anne Gentle
  • DITA for Practitioners Volume 1: Architecture and Technology; Eliot Kimber
  • Dynamics in Document Design: Creating Text for Readers; Karen Schriver
  • Enterprise Content Strategy: A Project Guide; Ann Rockley and Kevin Nichols
  • Information Space; Max Boisot
  • Letting Go of the Words; Ginny Redish
  • Managing Your Documentation Projects; JoAnn Hackos
  • Microsoft Manual of Style; Microsoft
  • Single Sourcing: Building Modular Documentation; Kurt Ament
  • Technical Communication; Mike Markel
  • Technical Editing; Judith Taritz
  • The Insider’s Guide to Technical Writing; Krista Van Laan
  • The Language of Content Strategy; Scott Abel and Rahel Bailie
  • The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill; John Carroll

Webinar recording of the changing nature of technical content

STC France-TCeurope has published a recording of Ellis’ webinar presentation on the changing nature of technical content. The presentation lasted 50 minutes, followed by 10 minutes of questions and answers:

What capabilities do Technical Authors want in an authoring tool?

We were contacted last week by a SaaS developer who wanted to know if their solution might be of interest to companies needing to write and host their product’s user manual or online Help content. So what capabilities do Technical Authors look for in an authoring tool?

There were a few features that sprung to mind:

  • Multi-channel publishing (for example: publishing to the Web, Microsoft Word and PDF). PDFs are still important as a publishing option, as people still like to read good quality printed content.
  • Separation of look and feel from content.
  • Content re-use (write once, re-use many times). This is different from simple cut-and-paste.
  • Variables (so it’s easy to change product names).
  • Conditional text (content that can vary depending on the type of user or type of product).
  • Link management (being able to find content in the project quickly, as well as being able to manage the dependencies among links and topics).
  • The ability to handle larger documents (200+ page documents with screenshots on most pages)
  • Expanding/collapsing table(s) of contents (and even different tables of contents for different types of users).
  • A user-friendly authoring environment.
  • Version management of the content.

Ideally, there would also be:

  • A way for occasional users to add and edit content without breaking formatting styles, using a User Interface that didn’t overwhelm them.
  • Access to and shared management of the content. This is so that writers could collaborate with each other, working on different topics for publications at the same time.

Are there any other features you would expect?

A researcher used Buzzfeed style headings on Help pages – the results will astound you

Flair PoolThere was an interesting news snippet today from Flair Pool, a PhD candidate who has been researching how the latest trends from the Web and Social Media can be applied to traditional user documentation.

Flair has been looking at how the techniques used by sites such as Buzzfeed could be incorporated into knowledge bases and online Help sites such as the Microsoft Developer Network and IBM’s Software Knowledge Base. She’s been running tests on changing the titles of topics, to increase the number of clicks, and then testing the results. Flair’s premise is that Help topic titles are typically quite dry – adding a user, deleting a user, opening a file etc. – and not very attractive to Millennials used to reading Buzzfeed and similar sites.

Millennials photo

Millennials Flickr image by Erin Nekervis

Not all types of Buzzfeed-style titles were judged appropriate to Help content, and so were excluded from the tests. In other words, the researchers did not rewrite any content linking a feature to users’ sex lives.

Below we’ve listed some of the modified topic titles Flair used in three different image applications:

Buzzfeed style Help

  • That Moment When Your Backup Doesn’t Work
  • Collaborating With Other Users – First You’ll Be Shocked, Then You’ll Be Inspired
  • File Sharing – You Won’t Believe What Happened Next
  • The 15 Filters That Prove This App Isn’t Such A Bad Place
  • 11 Blending Techniques That Only Advanced Users Know
  • Manipulating Colours Better Than Kim Kardashian
  • Apply These 6 Secret Techniques To Improve Getting Started With [XYZ]
  • Saving An Image File Anyone Would Be Proud Of
  • Adding A User Doesn’t Have To Be Hard. Read These 6 Tips
  • Get Rid Of Resizing An Image Problems Once And For All
  • Are You Embarrassed By Your Cropping Images Skills? Here’s What To Do
  • Five Template Tips That Will Make You Feel Like A Genius
  • In 10 Minutes, I’ll Give You The Truth About Image Layers
  • 4 Backup Tasks That Will Make You Want To Fall In Love
  • Do You Make These Simple Mistakes When Deleting A User?
  • Get Better File Conversion Results By Following 3 Simple Steps
  • Configuration Screens You Should Never Show A Unhappy User
  • When You Open A File And You’re Like, “Corrupted File”

Flair will reporting her findings and conclusions at the first ever CommaCon conference, which is being held in Oxford in the Autumn. She’s also applied to speak at the Kerning-Mann 2015 event as well. At this point, we can say the initial results suggest changing to this style of writing increases the number of page hits by 0.35%.

Flair is proposing these alternative style of topics titles be included as part of the new Lightweight DITA standard, on the basis that you can’t get more lightweight than this type of headline.

What do you think?

Could you see yourself using these types of titles in your user documentation? Share your thoughts below.

See also:

Lars-Po Faydöl: The man you see in every Ikea installation guide

The Cherryleaf newsletters – what do analytics tell us?

We recently shared some statistics* on newsletter with a partner, and took the opportunity to compare those figures with some industry benchmarks.

MailChimp publishes email marketing benchmarking statistics, as does Smart Insights. Based on those benchmarks, we have a slightly above average open rate and a significantly above average clickthrough rate. With the Cherryleaf newsletter, our goal is to send people useful content. So the figures suggest the content is of interest to our community.

There seems little point is sending out newsletters if they are not of value to the audience. So it’s important we include the right content. If you have some suggestions on how our newsletter could be improved, then do let us know.

* We never share names or email addresses.