Blog Archives

Optimizing your content like an engineer, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

Sara Feldman‘s session was titled, Optimize Your Content Like an Engineer. She talked about incorporating engineering principles and quantitative measures into continuous content optimization, and how this would bring better cross-departmental collaboration and return on investment (ROI).

An engineer’s approach is to change your strategy and direction, rather than just change your approach.

Inverting your perspective to outside-in

Just because we may be better at putting the customer first than other team members such as some engineers, that doesn’t mean we have no room for improvement.

Things are changing all the time, especially in terms of technology. Our method needs to evolve accordingly. We should challenge our assumptions and the ways we do things, to improve customer experience.


Sara mentioned trends such as artificial intelligence (AI), and self-service as a starting point for support calls.

Strategies to address the above trends:

  • Automate engagement with AI.
  • Distribute consistent knowledge across your support channels.

Sara said:

Content is like water

This comparison helps us separate the message we want to convey, from the format of that content.

Content engineering

Content strategy is what we should be doing, and content engineering figures out how we should do it. A content engineer bridges the gap between content strategy and development.

Content engineering makes it possible for writers to deliver good value.

Measures and methods

Sara touched on the following measurement techniques:

  • Leading and lagging indicators – Leading indicators are activity oriented. They represent the work you do, and are directly actionable. Lagging indicators are outcome-oriented, and they help you gain insight into the future. They’re harder to influence because you can’t change them directly (for example, you can’t directly change customer satisfaction (CSAT) measures). They confirm a pattern.
  • Vanity metrics – Page views, time on page, bounce rate, number of active/unique/new users. These things are easy to measure, but they don’t tell you much about outcomes. Vanity metrics have an important place, to take the pulse, look at trends, get started. To get benefit from them, you need to correlate them to outcomes that you’re looking for. Reference: Sara recommended an article called Measuring Page Velocity with Google Analytics.

Here are some methods drawn from engineering principles:

  • Eliminate unnecessary work – This technique is sometimes called maximising work NOT done.
  • Refactoring – This means cleaning up your code. The goal is to simplify the design of existing code without changing its behaviour. The principles apply to content too: fix unhealthy dependencies and other sources of confusion and clutter.
  • Data-driven design – Use data to determine what your customers need and want. The data should guide your decisions on a continuous basis. Use the data to define your minimum viable product (MVP). In other words, trim down your scope to get the content to your users sooner.
  • Retrospectives – Debriefings to determine what went well and what didn’t, and use the results to improve your content and processes.

Future of content

Sara said this topic is kind of fun and scary at the same time. She mentioned Information 4.0, and the Information 4.0 Consortium. A group of very smart people who’ve got together to decide how information needs to behave in order to support Industry 4.0 (the trend towards automation and data exchange in manufacturing technologies).

Some of the recommendations for Information 4.0 are that content should be:

  • Molecular – separate from format.
  • Spontaneous and triggered by contexts.
  • Ubiquitous – online, findable, and searchable. Gated content (content behind a signin) doesn’t qualify.
  • Personalised based on customer profiles.
  • Dynamic and continuously updated.
  • Accessible to other systems, e.g. via APIs. This is also known as content as a service.
  • Independent of channel, thus usable in multiple contexts.

So, content must be ready for anything? That’s hard to achieve. Here are some litmus tests from Sara:

  • Chatbots (conversational UIs)
  • Voice assistants (smart speakers)

To work with the above interfaces, content must be independent of format, and must come in small chunks.

A mature content experience

These are the requirements Sara mentioned for a mature content experience:

  • Prioritise user experience and intent over authors. Intent means modifying the type of results you’re giving based on what you think the user needs in their current context.
  • Blended content delivery. Our content is still too often presented based on our internal organisation structure. For example, help content, user manuals, training, all in separate places.
  • Every snippet is snippet one. (This concept is based on the well-known concept of every page is page one.) Snippets must be able to stand alone. We need to be conscious of the language we use and how we reference other things that may not be available.
  • Feedback loop to business objectives and products & services. Your customers are giving you lots of useful information as a result of your content analysis – make sure this feeds back to the business.

In conclusion

Thank you Sara for an interesting and engaging look at content optimisation.

The trending value of tech knowledge, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

Tom Johnson presented a session titled Tech Comm Trends: Providing Value as a Generalist in a Sea of Specialists.

Tom kicked off his talk by remarking that posts on his blog about trends have way more clicks than other posts. So he decided to dig deep into this topic. Find the trends that we should dig into, what we should pay attention to.

Trends, innovation, and what to focus on

Companies come and go. Some of them are big for a while, then disappear. Could the same thing happen to our role as technical writers?

One of the reasons companies fail is because they stagnate. They don’t pay attention to innovation. Maybe we, as technical writers, should ensure we don’t coast and that we look towards innovative techniques.

OK, so how do we decide what we should focus on? Which areas of innovation are important? For example, perhaps we should look at the trend towards focusing on user experience (UX) design. Some say technical writing is dying out because all products now have great UX design, thus rendering docs unnecessary.

The growth of technical writing roles

Tom showed some stats from the US Bureau of Labor Statistics over a period of five years that show technical writing roles growing by 8.2%. In the same period, software development roles have grown by 15.7%.

Growth projects over ten years show the ratio of technical writers to software developers will stay more or less the same (1/33 in 2016 as opposed to 1/35 in 2026).

Yet technical writers feel that the number of engineers they support grows year on year. Also people have questioned the methodologies used to collect the data, and whether things like off-shoring have skewed the picture.

How our role is evolving

Tom quoted some content from Ellis Pratt’s Cherryleaf podcast. 92% of technical writers agree that our profession is changing. But where are we headed? Just a few of the recent trends include:

  • Wikis
  • Semantic web
  • DITA
  • Content strategy
  • Chatbots
  • Docs as code
  • AI
  • Augmented reality
  • And more

We need to make some kind of decision about what to focus on, so that we can prepare for the next few years of our role. How can we sort transient novelties from reliable trends? Do potential employees value a broad skill set and a flexible outlook

Some sources of information

Job ads. if no-one is looking for technical writers with a particular skill (such as chat bot content) then that skill is not in demand, at least for now.

Research. Some academics publish thorough research on trends in our industry.

Looking at the above sources, Tom pulled out some conclusions:

  • Some job ads focus on professional competencies like written communication, project planning and management, etc.
  • Another focus is on subject matter knowledge. Many of the job ads emphasize experience in the subject area rather than tech-writer-specific skills. For example, candidates should know a particular programming language such as C or Java. You may even need to show examples that prove your knowledge. So, being willing to learn is not good enough.

Technical versus writing skills

People with technical knowledge, such as proficiency in a programming language, are often favored over those with writing skills. Tom posited that this could be because technical skills are easier to measure than writing skills.

There’s now a distinction between developers who write docs and technical writers. Another term is technical technical writers. There’s a feeling that, when publishing developer-focused docs, it’s more engaging for the audience to have developers writing the docs.

Is this the future we’re heading towards – the distinction between technical technical writers and technical writers? And why might this be so?

Tom discussed the fact that technology stacks have exploded. In 2005, there were a relatively few large vendors offering single systems. Now we have an explosion of development tools, vendor systems, and APIs. This complexity makes employers value technical knowledge more highly.

Learning technology

Given the increasing technical complexity, we need to figure out how to learn a new technology.

The Pomodoro technique involves using a focus app to learn for a specific period of time such as 20 minutes, then take a break and start again.

Learning creates a plastic mind. Tom said perhaps it doesn’t matter that much what you’re learning, provided you’ve created a learning mindset in yourself.

Do companies know what they need?

There may be a disconnect between what companies say they want and what they actually need. Compare the quote about Henry Ford and customers who want a faster horse!

Tom argued that companies need a technical writer who can analyse the customer experience and the audience and create the docs that address those, rather than focusing on the technology aspects of the product. This focus on customer experience is what excites the business executives in the company!

In conclusion

Thank you Tom for a well-thought-out presentation on the complexity of our roles and environments.

Sketching is like technical communication, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

The title of this session drew my attention: How Sketching Is Like Technical Communication, presented by Elizabeth Alley.

Elizabeth noted that this session was for visual learners and non-visual learners. I guess that covers me then. 🙂

She also gave us copies of a little sketch notebook that she’d made specifically for this session. I’ve included photos of some parts of it in this post.

How is sketching like technical communication?

As an artist and a technical writer, Elizabeth thinks about this every day. Sketching from life requires you to understand your subject. Doodling and other types of sketching require you to understand relationships between things.

Sketching is a tool for ourselves It helps us improve our attention or memory, and to help us understand a subject better. It also helps us remember to perform certain tasks.

Taking the art out of sketching

Barbara talked about bringing drawing back into our lives or expanding on what we already do. She touched on three types of drawing:

  • Practical sketching – Use basic shapes and lines to convey a word or idea. This is a tool That we can use in various parts of our lives, including work and planning a meal, for example. Barbara mentioned a few books that teach people how to doodle and sketch. She showed examples of a task list, a map, a plan for an artwork installation, a menu, the steps and ingredients in a recipe, and more. If we draw a map, for example, we’re more likely to understand and remember it.
  • Conscious doodling – For example, doodling during a lecture (“sketch notes”) can help you recall the content and make more detailed notes if necessary later. The technique of doodling is proven to improve your memory (retention of facts) and concentration. Doodling can also help you stay relaxed, for example on an aeroplane.
  • Observational drawing – This is also called sketching from life, or drawing the thing in front of you. You can do this very quickly, so that it takes under a minute, or you can add more detail and take up to an hour. Sketching strengthens the hand-to-brain connection. It strengthens your attention to detail. It captures what you felt at the time. When sketching from life, you need to look hard at the subject and capture it in a limited amount of time. (This is its relationship to technical writing.)

Elizabeth Alley, How sketching is like technical communication

While discussing the above topics, Elizabeth showed us a number of sketches and drawings, and drew examples from a few books. She listed the books on the “Resources” slide of her presentation.

We also saw how to take measurements and estimate relative sizes, in order to draw a mug (as an example).

How to get started with sketching

This was a question from the audience. Elizabeth recommended the book Doodle Revolution., by Sunni Brown. Elizabeth also said we should start with common objects like a coffee cup, a mobile phone, a keyboard. Elizabeth sketches these all the time. She’s curious how long it will take her to reach 100 coffee mugs!

In conclusion

Thank you Elizabeth for a lateral look at technical communication.

Improving docs and measuring quality, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

Early on Monday morning, Barbara Giammona presented a session called Measuring and Improving the Quality and Completeness of Your Documentation.

The idea for Barbara’s session came from a request from her boss to figure out ways to measure the effectiveness of documentation. She shared some of the resulting initiatives. She emphasized that measuring docs is tricky, and the initiatives are a work in progress.

Barbara covered the following topics:

  • Content
  • Processes
  • Productivity
  • Working with partners

Content improvement: Partnering with customer support

Barbara’s team talked to the global customer support team about improving the content of the manuals, partnering with them in a more deliberate way than before.

Some of the feedback was fairly obvious, in retrospect. Things like removing the number of notes and appendices by moving the content into the main doc, breaking up long sentences, and shortening titles. The customer support team also suggested sending high-impact docs for shared review.

One surprising request was to increase the number of acronyms, as they make the content more concise.

The measurement is that the number of customer-reported issues related to the docs goes down within 1, 2, and 3 years.

Content improvement: Hearing from customers

Barbara has made a deliberate effort to get in touch with customers directly. When customers come on site, for example to do beta tests of the product, Barbara makes an effort to meet them. She sets up review sessions, walks around at customer conferences asking people for feedback on the docs.

The measurement is improved customer satisfaction, year on year. To get these results, the teams uses a customer satisfaction survey.

Content improvement: Refactoring of much-used and visible docs

In the documentation plan, the team includes the time and effort needed for improvements to the docs. Tasks include:

  • Improving and adding/removing graphics
  • Breaking up long chapters
  • Simplifying language
  • Moving installation instructions into one place
  • Review FAQs for potential inclusion into the docs

Another important goal is to take customer feedback into account when designing new docs.

The measurement is fewer complaints from the support and delivery team.

Process improvement: Length of review cycles

Barbara talked about performing a root cause analysis for the problematically short reviews. Review cycles were too short, and doc tasks were being compressed into shorted periods.

The root cause analysis looks very thorough. People wrote Post-it notes about potential causes, which the team then grouped and analysed. The team used the “five whys” technique to ask up to five questions about why a problem arose. This technique helps find the root cause. Barbara walked us through the process in detail with examples.

The measurement is improved experience of reviews in new projects. Barbara joked that the reviews should no longer make you feel suicidal.

Process improvement: Productivity

The topic here is resource availability and the ability to estimate workload. It’s difficult to estimate the effort required for each project. The technique is to gather data from completed projects (hours spent) and use those for future estimates.

The measurement is accurate cost estimates and not having to scramble to find resources.

Process improvement: Partnerships/outsourcing

Barbara talked about working with a team outside the company to complete documentation tasks. At first the relationship failed due to lack of skill in the partner team.

The technique to solve this problem was to visit the partner team in person and provide training sessions. Training includes things like effective writing and how to with subject matter experts.

The measurement is to see whether the partner team sets targets and delivers on par with the other teams, and whether the US leads are writing less and leading more.

In conclusion

Thanks to Barbara for an enjoyable and thorough talk about techniques for improving our documentation.

Season of Docs is now ready for tech writer exploration

Technical writers around the world can now explore the open source organizations taking part in Google’s Season of Docs program. It’s time to start preparing your project proposal!

Season of Docs provides a framework for open source projects and technical writers to work together on the projects’ documentation. It’s a program run by Google in collaboration with participating open source organizations.

The program kicked off in March 2019 by inviting open source organizations to apply to take part.

The list of participating open source organizations is now available on the website.

The next step is for technical writers to apply to take part in the program.

Explore the tech writing project ideas and contact the organizations

It’s exciting to see the variety of open source organizations taking part, and the technical writing project ideas that each organization has on on offer!

If you’re interested in working on open source docs as part of the Season of Docs program, now’s the time to start planning your project proposal. You can contact the organization(s) that you’re interested in right away, and discuss your proposal with them. Talking up front is a great way to ensure you submit the best project proposal that you can. Then you’ll be ready when the technical writer application phase opens on May 29.

Some hints from me

Each open source organization has published a list of ideas for technical writing projects they’d like to complete within the Season of Docs program. (Follow the links from the page of participating open source organizations to see each organization’s project ideas.)

  • Remember that you’re the one with technical writing expertise. Write your proposal based on your experience of other projects. Include your plan for design and execution of the project, and scope the project so that it’s achievable within the Season of Docs time frame.
  • You can split an organization’s idea into smaller chunks and write a proposal for one or more of those chunks.
  • You can also propose an entirely new project idea of your own, based on your exploration of the organization’s open source product and existing docs.
  • Read the Season of Docs FAQ and technical writer guide for information on how much time you can expect to spend on a project, and about long-running versus standard-length projects.
  • Do get in touch with one or more organizations to talk about the projects they have on offer. They’ll be able to help you design a proposal that you can then submit to Season of Docs. It’s the organizations who’ll eventually choose the technical writers to work on their docs during the program.
  • You can talk to as many organizations as you like, and you can submit more than one application to Season of Docs, though only one application will be accepted.
  • Your project proposal forms part of your application to Season of Docs. Read the technical writer guide and application hints for help with creating your application.
  • Make your project proposal count. There may quite possibly be other technical writers proposing to the same organization.

Questions and discussions

Here are a few places where you can learn more and ask questions:

  • Join us on the Season of Docs Slack workspace or discussion mailing list, anytime. For information on how to join, check out the page about discussion channels on the Season of Docs website.
  • Will you be at STC Summit in Denver on May 6-8 (next week)? I’ll be speaking on Tuesday, May 7, at 2pm about open source, documentation, and Season of Docs. See the session description in the summit app (you need to be logged in). You can also grab me for a chat in the conference hallways.
  • Join the Write the Docs online meetup in mid May. Write the Docs Australia and Write the Docs India are hosting a joint online meetup (webinar) on May 15 (APAC time zone). Join us for an overview of Season of Docs! The webinar is free of charge and is open to anyone interested.

Hope to see you in one of those places. 🙂

%d bloggers like this: