Compassionate technical writing, 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.

Robert Perry’s talk was entitled Technology for Good: Helping Organizations Do (More) Good with Technology. He spoke about how his organization has created solutions to make technology available to non-profit and educational organisations. He also introduced us to the concept of compassionate technical writing.

These are the primary points in Robert’s task

  • Embrace Industry 4.0 in your career and writing. (Industry 4.0 is also called Fourth Industrial Revolution, FIR, or Information 4.0.)
  • Use technology responsibly and for social change.
  • Create content that people can learn from and relate to.

Challenges and opportunities in Industry 4.0

We’re already living the Fourth Industrial Revolution, says Robert. Innovations are transforming the world we know, and changing how we work and play. This is how Robert characterised Industry 4.0:


During the session, Robert talked us through the first (steam in the 1700s), second (electricity in the 1800s) and third (computing in the 1900s) industrial revolutions. Each of these triggered profound changes in society.

Then he focused on Industry 4.0. It has benefits and disadvantages. It’s disr

Industry 4.0 is moving far faster and is having a wider effect than any of the other three revolutions. It’s affecting almost every country and society. Technologies include biotechnology, robotics, 3D printing, Internet of things, artificial intelligence, virtual and augmented reality.

These technologies are also changing customer expectations. Customers expect more valuable connected experiences, personalised content, and contextualised content. Customers are not afraid to move to a different provide to get those.

Technical writers can help improve the customer experience. New categories of jobs are arising at the same time as others disappear. New opportunities are becoming available.

Customer feedback is becoming crucial, as is creating personalised, contextualised content delivery. There’s lots and lots of data coming in. Data feeds artificial intelligence, which can help make businesses and documentation smarter.

Trends for technical communication:

  • Intelligent content
  • Automated content generation
  • Dynamic delivery of content
  • Neural machine translations
  • Service-oriented content rather than document-based product manuals
  • And more

Robert said that metadata will drive many of the content delivery models. Metadata will become richer and more complex.

Technical writers will become knowledge managers – people who curate information, and enable the delivery of data-based dynamic content.

Technology for good

People must own the shaping of technology. Businesses are at the forefront, so they should also drive the sense of social responsibility. These are some of the things a business can drive:

  • Education and training programs for all
  • Ensure equal pay for equal work
  • Equality for every human being
  • Protecting our planet

There are hefty moral implications for these new technologies, for both good and bad. We build the things we admire, so we must make sure we understand the implications of what we build. We need to ensure that the economic benefits are available to all, not just to a small group.

Compassionate technical writing

The doc team at Salesforce (Robert’s employer) has started an initiative to write docs that show awareness of the customer’s situation. So they’ve started telling stories.

They ask themselves whether they write with a real human understanding of what it takes to use the product. Are we inspired and passionate about our work? Do we feel connected with the user?

Remember that readers should experience patience and compassion while they read. They may be in the middle of a frustrating experience.

How to write compassionately?

  • Be yourself.
  • Tell a story to help people identify with the documentation.
  • Take care of your reader.
  • Don’t force it on them. Be judicious – some areas of tech writing don’t lend themselves to compassion.
  • Anticipate the questions your reader may have, and answer them.
  • And more points from Robert.

The primary point is that every document must be technically accurate and excellent.

Robert recommends a book by Ann Handley, “Everybody Writes”.

In conclusion

Thank you Robert for a thoughtful look at technical communication and our changing world.

Headless CMS, IoT, and You, 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.

This was a talk from Chad Dybdahl from Adobe, with the intriguing title of Off with Their Heads! Headless CMS, IoT, and You.

Some definitions

A headless server is essentially a box. There’s no screen. It just sits there running something.

A Web CMS, like WordPress, is a traditional tool for building a website.

A headless CMS serves as a content repository. There’s no presentation layer. You’re writing content, and the CMS serves as a repository for the content. There’s a REST API that delivers the content. This makes for a very flexible environment. However, you need developers creating a front end to display the content.

A traditional CCMS also does not have a front end for content delivery. No APIs either. The published content is hosted somewhere else, such as in PDF or a website. Authoring is often done via DITA.

A hybrid CMS combines the best of both worlds, said Chad. It provides a content authoring and repository, a web front end, and REST APIs.

Content explosion

Chad talked about the number of devices that people use (average 6 devices) and the number of content sources (average 12 sources).

Content as a service

Content as a service is where you have a hub that delivers content to various channels. It’s an API-first service. Content delivers can choose the content they need and how to deliver it.

What do you need?

  • Structured content, such as that provided by DITA, in a well-defined model.
  • A CCMs that provides APIs and an API-first experience.

Demo of an Adobe CCMS

Chad demonstrated Adobe Experience Manager as an example of a hybrid CMS. He showed us a very simple web interface that queried the CMS and output content in the form of HTML (rendered for human readability) or JSON (as an interchange format).

IoT (Internet of Things)

In Chad’s house are various IoT devices that receive and output information and enable automation. On a web interface you can see the views of various cameras installed around the house, the output of the motion sensors and thermostat.

We should see all the items in the house as content. How do you tie together all the output from the various items? Chad uses a tool called Node-RED.

Doing the same thing with content

Chad uses Node-RED to tie pieces of content together too. He showed us the Node-RED tool for building a workflow to use the APIs from the Adobe Experience Manager CMS. We saw the resulting web page, built from a few bits of content from the CMS and rendered into HTML.

In Node-RED:

In Adobe CMS:

Rendered as HTML:

In conclusion

Thank you Chad for a good introduction to a CCMS and an intriguing glimpse of the wrld of IoT.

More than writers, 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.

Alan Porter presented a session titled Why Technical Communicators Should Be More Than Writers. The alternative title is Why Technical Writers Shouldn’t Be “Writers!”

Alan started his career as a technical author, writing technical manuals for the Concorde aeroplane (British Airways). He said there are mentions in history of Roman times of people consulting the manuals. Even hieroglyphs and cave art are technical writing. He showed us some examples of writing that are hard to read, and touched on best practices:

  • Structured content
  • Topic-based authoring
  • Simple language
  • Consistent terminology
  • And more

What is our role?

We may think we’re hired to be technical writers, but actually our job is to communicate complex material in a way that’s as simple as possible.

Alan said this is the main takeaway from this session:

Your customer does not care where your content comes from.

What the customer wants

People want answers to their questions: 70-80% of people come to a website because they have a question. The questions are primarily in 2 groups:

  • Discover, learn, and train
  • Get answers to product or service questions, fix a problem, and enhance their usage of the product.

Most documentation is feature-focused, whereas people want to know how to do something or what the benefit is to them.

Customer experience and brand experience

Documentation and the product should work together to make a good user experience. Alan showed us an example of a tech guide for a product where cables and ports were colour-coded to ensure easy installation. The manual showed diagrams that corresponded to the physical pieces.

The most important thing for companies to focus on is customer experience.

Technical writers are not just writers. We’re the key differentiators. We drive customer experience because we understand the customers and the market.

Every time a customer interacts with content, that’s a brand experience. Alan showed us a page of diagrams that was obviously an Ikea guide, but did not have the brand name anywhere. We all knew the brand anyway.

Next we looked at a Lego guide, which presented the same experience.

Alan said this is the way we should be thinking: Content should align with the brand and the product. Looking back to cave diagrams and glyphs, Alan said that humans have been communicating in a visual way for a very long time.

However, the diagram must convey the message you want. Alan showed us an engineering diagram that was intended to show the rings on Challenger would crack at a certain temperature. The diagram was dense and full of information, and did not convey the intended message.

Visual thinking

Before creating a diagram, we must understand the data. Then we need to decide how to convey it.

Another important step is abstraction. Alan showed a series of pictures of a face, moving from a photo thru various simplified drawings to an emoticon. Babies will react to a smiley face icon before they react to their mother’s face.

Symbols and icons help people understand something quickly. They become part of the culture. But before using them, make sure the meaning is clear.

  • There are standards for symbols and icons. For example, for car maintenance manuals, an automotive committee (I didn’t catch the name) has created a standard set of symbols for use across companies.
  • Be aware that certain symbols mean different things in different countries. An example is the thumbs up symbol, which has an unacceptable meaning in some places.

Think about colour. For example, in China white is the colour of funerals and morning. Other cultural aspects include whether people in a photo are wearing shoes or not, or the amount of white space on a page.

Alan mentioned many more cultural and design aspects that you need to be aware of. Visual communication is complex!

Where the content will be used

Consider where people will be viewing your content. For example, if they’ll be outside, it may be hard to read on a computer screen.

More to consider

Alan touched on animation, sound, and video. Video is an enormously popular way to consume content. As the next generation grows up, their primary interaction with content will be through voice.

We also had a quick look at augmented reality (AR) in technical instructions.

Alan’s recommentation

Examine a screenplay or a comic book script, and see how those were translated into visual content.

In conclusion

Thank you Alan for an engaging look at our changing role.

How analytics can change your world, 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.

Analytics! They’re all the rage, and something I’m very interested in. David Payne presented a session called Analytics Can Change Your World. The subtitle of the talk was Or Justify Your Existence.

David’s goal in this presentation is to help us find the data that will help us prove our worth within an organisation. He said that the tool you use is not important. It’s what you do with it that matters.

The story of a team’s journey into analytics

David told the story of his team, which started from a small size with little clout. The team also had no insight into how their content was used or how often downloads occurred. They didn’t know who used the docs.

They started by collecting data using surveys. They had no way of finding out where users started from. The survey consisted of 20 questions. They had 300 responses over 3 years. The results were largely that the docs were “the worst ever seen”, “horrible”, and so on. There was no actionable feedback.

Next they added feedback links to the doc pages. Received thousands of responses. Not one of them was about the docs themselves.

The team also now knows how many people download the docs. The number has increased from 4 downloads in 2013 to more than 60,000 in 2017.

What to do if no-one is reading the online help?

At first, page views for the online help were very low.

  • Advertise – for example, add a banner on the printed docs.
  • Encourage add a hook in the product itself (Clippy?) to encourage people to view the online help.
  • Engage – talk to customers about how people use the online help.

David showed how the page views for the online help increased year by year.

Using your metrics

When you have the data, you need to start asking questions. David walked through these:

  • Which OS and browser are they using? David mentioned that his business stakeholders wanted this metric, even though to him it’s not relevant. Lesson: Have the pieces of data you want, but be ready to answer all sorts of questions.
  • Did the searches yield the results that the user wanted? For example, some information is legitimately not in your help because it’s relevant to other organisations, but people still search for it. In David’s example, over 60% of search results were not the ones the customer wanted. Tactic: David ran focus groups with customers. Many of the customers said that they turned off the online help for their users. The reason was that the product was very configurable, and thus the screenshots and information in the help were for the baseline system, which was not useful in a highly configured system.
  • How many page views per product? This result was not very useful, as it showed nearly 50% under the category “other” – these relate to search results and the home page, rather than single pages. This result did show, however, that there were 2000 topics in the docs. That’s too many for people to navigate around. David’s team is now working on reducing the number of topics and on improving context sensitivity.
  • How effective is context sensitivity? See how often people are arriving on the first page of the help as opposed to specific pages.

Next steps

Some strategies are to examine the data:

  • Focus on improving the high-traffic pages. Create a home page that highlights the most popular topics, so people can find them easily.
  • Find data for pages that have no views. Find out why people aren’t going there. If the page is important, raise its visibility. If the content is irrelevant, consider removing it entirely. David’s team managed to cut 400 out of 2300 topics.
  • Examine the search queries. For example, the number one search query was “transcript”. Discuss this with the product team and ask why people can’t find the transcript. Make the application so user friendly that the docs are not necessary.

Market the data throughout the company. Product managers may be able to glean the features that need more support. Development and QA can see which areas of the product the customers find tricky. Customer support may be able to use your data to support their own findings.

David discussed a few more questions we can ask about the data. He remarked that there’s no such thing as too much data.

In conclusion

Thanks David for a great overview of the type of analytics we can gather and how we can use the data.

Mentoring and being mentored, 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.

As a senior technical writer, mentoring and being mentored are much on my mind. Carrie Sheaffer and Eva Miranda presented a session titled, Be the Best You Can Be: Mentoring and Being Mentored.

As an introduction, Eva talked about her positive experiences with her mentor at uni, and how she strives for a growth mindset. Carrie talked about the moment when she realised that she was now a senior tech writer, and thus the one people looked to for advice. It was scary and wonderful and empowering.

Eva and Carrie met through STC, then started work at the same organisation, and kind of fell into an informal mentoring relationship. Instead of an informal mentorship, they recommend a more formal approach in which you define and measure your goals.

There are many types of mentorship, including:

  • Peer to peer
  • Speed
  • Traditional
  • Group
  • Network
  • And more

Perhaps you’re already mentoring someone…

… but don’t know it. If you’re helping a junior team member and advocating for them, then you’re already mentoring them.

You can be a mentor without being a manager. The mentor gives advice, whereas the manager gives rules.  Mentors are interested in your growth, while managers are responsible for your performance.

Defining your goals as mentee and mentor

A mentee (person being mentored) has certain goals, such as job satisfaction, opportunities to look out for, career advice and leadership opportunities.

The mentor also needs to know what they will get out of the relationship, even if it’s a little less tangible. Examples of their goals are to get a skilled team member and increase the performance of the team. Many mentors also gain satisfaction from giving back and sharing skills.

At the start of the mentoring relationship, the mentor and mentee should sit down and establish their goals. They should also review their goals and the achievement of the goals at regular intervals. The relationship should be reciprocal.

The mentoring relationship

Another good idea is to get to know each other. See if there are any shared interests, hobbies, or activities.

Be positive and open, and be sure to praise effort as well as skill. Make connections at the workplace, hold regular one on ones, and work together on the relationship.

Schedule fun outings, and aim for levity.


Carrie promised that feedback doesn’t need to be scary (even though it actually is!).

Some tips:

  • Distinguish between something that is a personal style preference versus a rule. For example, the mentor may have a preference, or the rule may come from a style guide. The mentee can choose to follow the former, but has no choice about the latter.
  • Talk about a piece of writing, rather than just asking them to rewrite it. Sometimes the talking through the topic is so much better than what was written, and the mentor doesn’t need to do any more.
  • Make suggestions, like “what do you think about trying…”
  • If you see a repeated pattern, don’t comment on every single occurrence. Just mention it once or twice, and say there are more occurrences.

Remember that the goal is for the mentee to grow, not to show what’s wrong. The mentee is thankful when the mentor takes time to explain the reason for feedback on a doc, rather than just enter the correction.

A tip for the mentee: Don’t freak out!

Feedback should go in both directions. The mentee should review the mentor’s work as well as vice versa. The mentee has something to contribute, and the mentor makes mistakes. The mentee can ask something like, “I noticed you did this, can you explain why?”

The mentee can learn as much from giving feedback as well as from receiving it.

When there are disagreements

What do you do when you have disagreements about the way to do something, and you can’t resolve the disagreement?

Get other opinions. Remember there are different viable ways of doing things. Make the discussions constructive, and don’t become emotionally invested in a solution.

Remember: The goal is to improve.  When you have a product that is better, everyone wins.

The mentor must own their growth

The mentor can’t tell the mentee how to grow. The mentee defines their goals and the direction they want to go in. Then they identify the help they need, and discuss that with the mentor.

Ask for help when you get stuck. (Eva and Carrie showed us a haiku that they wrote to illustrate this section. It was fun.) Especially if there’s a deadline, ask for help directly.

If you’re working on something in a certain direction, and you think there’s a better way to do it, speak up.

The problems

There can be problems in a mentoring relationship. Mentoring is hard, and it’s no fun if the relationship is not working. Maybe you just don’t get along, or maybe the mentor is just not good at mentoring or good at their job. Perhaps the mentee is not progressing.

There are some options:

  • When you’re reviewing your goals, suggest a change or suggest ending the mentorship.
  • Suggest that the mentor moves to a different role.

When the mentee advances to a new level

On the positive side, any perceived problems in the mentoring relationship could be because the mentee has advanced so far that they no longer need the same level of mentorship. An approach is to address this when reviewing your shared goals. Perhaps the mentor needs to change their mentoring methods and the mentee needs to change their goals.

The mentor can start giving the mentee more advanced projects, and reducing the amount of detailed, low-level feedback.

In conclusion

Thank you Eva and Carrie for a lively and thoughtful look and the mentoring relationship.

%d bloggers like this: