Category Archives: technical writing

Financial impacts of good or bad communication

I’ve been examining several articles about the financial impact of good or bad communication. Mistakes in documentation cost money, and there’s some good evidence of that point. In addition to the cases that involve documentation, I’m also interested in communication in a wider sense.

Here’s what I’ve found so far:

Thank you to Kit Brown-Hoekstra of Comgenesis for the following cases of communication mishaps that have cost money:

Looking for more

Do you know of any other recent research into the financial impacts of good or bad communication? I’m interested particularly in metrics around how good communication can save an organization money, and of times when communication that’s gone wrong has cost money.

Linking the curse of knowledge, imposter syndrome, and metaknowledge

I’ve been doing quite a bit of teaching and mentoring lately. Those teaching and mentoring experiences have led me to think about what I know without even realizing that I know it. At a deep-seated, subconscious level, I’ve forgotten that I once didn’t know certain stuff.

I’ve also been thinking about the effect of that very forgetting on the people I’m teaching or mentoring. And the effect of that forgetting on myself and on my own confidence levels. 

During all this thinking, it occurred to me that there’s a link between two often-discussed phenomena: the curse of knowledge and imposter syndrome.

The curse of knowledge

It’s all too easy to forget how much we know and what skills we wield. In particular, if you’ve been studying or practising in an area of knowledge for a long time, it’s easy to forget what it felt like when you knew nothing about that area. This phenomenon is called the curse of knowledge.

Typically, when people talk about the curse of knowledge, they’re referring to the fact that it’s hard for experts to put themselves into the shoes of a novice. As experts, we tend to assume too much knowledge on the part of others. When a new person joins our team, for example, we may not give them enough information to enable them to start doing their job. We may gloss over the basics or not even mention the most crucial aspects of something that we’re trying to explain.

Here’s an example: At work, I sometimes teach a class on the basic principles of information architecture. The class is for software engineers and other members of a product engineering team. When teaching the class, I often feel a temptation to rush through the early part of the training, which lays the groundwork for more in depth concepts. To me, the early part can seem tedious and repetitious. Surely the people attending the class must find this material boring? 

I have to remind myself frequently that I feel that way only because this stuff is my bread and butter. For the class attendees, on the other hand, it’s essential to lay the groundwork before getting to the more complex part of the material.

Imposter syndrome

The term imposter syndrome refers to a feeling that we don’t deserve the success we’ve achieved or the praise we’re given. Many people have this feeling, even very successful people. It originates in a deeply held belief that our accomplishments have come to us by luck rather than by merit. It’s a feeling that, although things looks good to other people, everything might crumble and fall in an instant, because we don’t really have the skill to hold it all together. We could be unveiled as an imposter at any time.

Two sides of the same coin

Recently, I realised that the curse of knowledge and imposter syndrome are linked. If we’ve forgotten how much we’ve learned over a period of time, it’s all too easy to think other people know so much more than us. Are so much more skilled than us. Are so much more worthy of success than us.

Our knowledge increases over time. Somewhat contrary to expectation, the curse of knowledge can increase in power over time too. The more experience we gain, the more we forget how much we know.

What can we do about this Catch-22?

I find mentoring or training other people is very enlightening. When students or mentees ask questions or discuss points with me, I sometimes have an aha moment. Hey, this is something that I know and that I can help this person with. This person is very bright and well trained, but they just don’t know this stuff yet. It helps me to get a glimpse of what I know, seen from their point of view.

Writing stuff down is also useful. For example, writing blog posts. Trying to formulate what I know, from the point of view of someone who’s a beginner in a particular area, shows me just how much I know and how complex the information is when I structure it for someone else.

Another thing I’ve found useful is taking training courses, even if the material is largely about things that I already know. Re-doing the training puts the information in a new perspective and cements my awareness of the knowledge. 

Knowing what we know is a kind of metaknowledge. I think that gaining and cultivating this metaknowledge helps us communicate with others and have more confidence in ourselves.

Card sorting for user journey analysis and information architecture design

Recently I’ve been using a card sorting tool, part of the Optimal Workshop toolbox, to analyse a set of user journeys. The card sorting tool is also useful for designing an information architecture for a website or documentation set. This post describes how I used the card sorting tool, because it may be useful to other tech writers and information designers. (I’m not affiliated with Optimal Workshop, nor have they asked me to write this post.)

I’m working with a team to design a tool for gathering and presenting documentation metrics. As a first step, we want to know what type of metrics people will find useful, and how they’d like to use those metrics. We decided to start by gathering user journeys. For us in this context, a user journey is a goal that someone wants to meet by following a set of tasks.

After gathering the user journeys, we needed a way to analyse and collate them. Optimal Workshop‘s card sorting tool came in useful here. This post describes how.

Note: The examples in this post come from Optimal Workshop’s demo application. (They’re not from the actual interviews and user journeys that my team is working with.)

This screenshot shows an example of a card sort, from Optimal Workshop’s demo application:

In the above example, participants in the card sorting exercise can move the cards from the column on the left into the work area on the right. When moving a card, participants can choose to put a card into an existing group, such as “Buying a cell phone”. Or they can create a new group and give it a name.

Context around what I needed to do

My team’s goal was to understand a large set of user journeys that we had collected for a yet-to-be-designed system. Before using the card sorting tool, my team had done the following work:

  1. Interviewed prospective users of the proposed system, asking them a set of open-ended questions about why and how they would use the system.
  2. Made notes during the user interviews, using a standard template to ensure that each interviewer captured the same sort of information from each interviewee.
  3. Distilled the notes from each interview into one or more user journeys. A user journey encapsulates a single goal expressed by the user. It may take one or more tasks to achieve that goal, but at this point the goal was the important thing.
  4. Collected all the user journeys into a single repository. In our case, we used a spreadsheet.

After doing all that, we had a large collection of user journeys — too many to work with in the next phase of the project, which is to prioritize the use cases, define requirements for the use cases that we want to tackle first, and design a minimum viable product. Some of the user journeys were duplicates. Some user journeys represented subsets of others. Some user journeys expressed a similar goal, but from a different perspective.

We needed some way of analysing and collating our user journeys. Enter the card sorting exercise!

What is card sorting?

Card sorting is an exercise that you can use to see how your customers think about a certain subject area or product. You give people a set of cards, each representing an activity, task, topic, or concept, and you ask them to group (sort) those cards into categories.

I’m using the word customers in a broad sense. The participants of a card sorting exercise can be customers, users of a product, readers of a website, members of a design team, and so on.

As the creator of a card sorting exercise, you can choose whether to give your customers preordained categories (a closed card sort) or to let the participants make up their own categories (an open card sort).

By examining the groupings made by the participants, you get useful insights into the way people think about your subject area or product.

In the past, I’ve participated in card sorting exercises where we used real cards made out of paper or cardboard. Sometimes the cards were Post-it notes. We’d write the topics, tasks, or concepts on the cards and place them on a table or stick them on a whiteboard. Then we’d shuffle the cards into groups, using the exercise as a way of exploring concepts and designs.

It’s quite common to use electronic cards instead of paper ones. That’s what we did for the user journey analysis that I’m describing in this post, using Optimal Workshop.

How we used card sorting to analyse our collected user journeys

We decided it’d be useful for each member of our team to analyse the user journeys individually as a first step. That’d give each of us the freedom to look for patterns and understand the users’ goals, without being influenced by other members of the team. After that, we wanted to analyse and collate our findings.

I loaded all the user journeys from the spreadsheet into Optimal Workshop’s card sorting tool. I created an open card sort, so that each person could make up their own groupings of user journeys. Then each team member spent a couple of hours sorting and grouping the user journeys. You can see what this looks like by trying Optimal Workshop’s demo app, using the participant view.

The next step was to examine what we came up with. Optimal Workshop offers some useful tools in the Analysis tab of the Results section. To try it out, see the results view of their demo app.

In particular, I found the 3D cluster view interesting and useful. Here’s a screenshot from the Optimal Workshop demo:

The tool analyses the categories created by the participants, and further groups the categories into clusters. This is particularly useful in an open card sort, where participants have created their own categories. It gives you a way of finding similar categories.

The next screenshot shows the details of one particular cluster, listing first the categories in the cluster, and then the cards in those categories:

We used the sets of “similar category labels” offered by the tool as a starting point to help us combine and reduce the number of user journeys in our collection.

Card sorting for information architecture design

In the situation that I described above, we used card sorting to analyse user journeys. Card sorting is useful in other situations, one of which is designing the information architecture (IA) of a website or a documentation set.

The IA usage is closer to what Optimal workshop’s demo application shows. In case you skipped past the section of this post about user journeys, here are the links again:

  • You can try out Optimal Workshop’s demo as a participant in the exercise, using the participant view.
  • Or you can try it out as the analyst or designer viewing the results of the card sorting exercise, using the results view.

Card sorting is also useful for the members of a team designing the website. Instead of having users do the card sorting exercise, you can have your team do it. This gives each person the freedom to draft designs in peace, play with concepts, and experiment with new groupings. Once everyone has finished, you can get together to see the differences and similarities in the way you’re thinking about the design.

Trying out Optimal Workshop

You can use Optimal Workshop for free to try it out. See the various options on their pricing page, including “try for free”.

More tips about card sorting or other UX tools?

If you’ve used a UX tool as part of your role as technical writer or information designer, I’d love to hear about it.

Writing a one-pager to pitch a doc idea

As a technical writer, I’ve sometimes found it useful to write a short document describing an idea or a proposal. The target length for such a document is one page. Hence the name, one-pager. In some situations, a one-pager is a good alternative to a doc plan.

This post is about one-pagers used in the context of technical writing. In other contexts, a one-pager may be a pitch for a company or a student’s summary of a lecture.

Quip: An engineer pointed out that one of my one-pagers was technically a two-pager. (It was actually about one and a third pages long.) I responded that I could fix that by reducing the font size. 🙂

For me, the purpose of a one-pager is to express an idea and get input on the idea. For example, I’d write a one-pager when a doc plan would be too heavy-weight, but I want to get feedback before starting the documentation update.

A one-pager isn’t the place for a detailed design — that’d go in a doc plan or a design doc. (See my post about doc plans.) Rather, a one-pager is useful to coalesce my own thoughts about an idea, and to get feedback from my colleagues about the overall idea before I go ahead and implement it.

For example, I’d create a one-pager to propose one of the following:

  • A new tutorial for a use case that we don’t yet cover in the documentation.
  • A new type of tutorial that follows a different pattern from the other tutorials in the documentation set.
  • A change of tone in a particular document or documentation set. I’d describe the tone of the current documentation, the effect that the tone is having on readers, the new tone that I’m proposing, and the reason for the change.
  • An event, such as a doc sprint. I’d describe the purpose and format of the event in order to gauge support before plunging into further planning.

What does a one-pager look like? Well, firstly, it’s short and to the point. Because it’s so short, a one-pager often doesn’t include headings. My one-pagers tend to look like this:

Title (For example: One-pager: New tutorial type for Foo users)
Date and author

Goals: A business statement of the effect you want to achieve. (For example: customer retention, increased adoption, etc.)

A short, motivational callout, often in large text and a different style from the rest of the doc. (For example: We want to help customers use Foo when things go wrong.)

A succinct description of the idea or proposal. This is the main part of the one-pager. Start with a descriptive paragraph, followed by bullet points to capture the main points in your proposal. As well as being a useful short form, a bulleted list gives visual emphasis that this is the core of the one-pager.

In scope: Areas that are in scope for this proposal. If you don’t have anything to put here, leave out this section.

Out of scope: Any areas that are out of scope. The goal of this section is to ensure there are no misunderstandings between you and your stakeholders. If you don’t have anything to put here, leave out this section.

References: a list of relevant documents

Have you ever written a one-pager, or have you felt the need of such a document type in the past?

How to conduct a walkthrough of a doc plan or design doc

In a recent post about writing a doc plan or a design doc, I mentioned that it’s useful to conduct one or more walkthroughs of the doc plan or design doc before sending it out for review. Here are some tips on conducting a walkthrough.

During an in-person walkthrough, you can iron out potential misunderstandings. People can ask you questions, and you can get immediate feedback from people who may not find the time to review the doc in detail.

In other words, a walkthrough can help clear away the cobwebs! I took this photo recently while walking on a bush path.

Inviting people to a walkthrough

The first step is to decide who should attend your walkthrough. If you have the luxury of working with other technical writers, it’s useful to walk through the doc plan with one or more of them first. They’ll point out inconsistencies, missing pieces, and unclear sections for you, and help you crystalise your own understanding of the problem that your design is solving and iron out any wrinkles in the design.

Give yourself time to incorporate feedback from the technical writers before holding the next meeting.

Next up, invite your key stakeholders to another walkthrough. These people should be the ones who can give you input on the problem and on your design. For example, your product manager and the engineers responsible for the area of the system that your documentation will cover.

Schedule at least a full hour for the walkthrough. The time will shoot past once everyone starts discussing the use cases and design.

In the invitation, provide the link to your doc plan, but don’t expect people to read the doc plan before the meeting. Some of them may look at it, but you should assume that no-one has seen it properly.

Running the walkthrough

Your goal for the walkthrough is to ensure that people understand what you mean to convey in the doc plan. Until you’ve run the walkthrough, you can’t be sure that what people will get from reading the doc plan matches what you intended to say.

I’ve found the following format useful for a walkthrough of a doc plan:

  • Start by explaining purpose of meeting: to give the attendees an overview of the doc plan and the design that it proposes, and to gather preliminary feedback. Let the attendees know that you’ll send the doc plan out for detailed review after the walkthrough.
  • Describe the context of the doc plan: the problem that you’re looking to solve, and the customers who form your target audience.
  • Show the outline (table of contents) of the doc plan, so that your attendees know the scope of the doc.
  • If the doc plan is very long, decide beforehand which sections you’ll walk through in person. Often, the diagrams (user flow and information architecture) are most useful sections to cover in person. Also make sure you cover the timeline for delivery of the documentation.
  • Actively solicit feedback at all stages of the meeting.
  • Make copious notes, either as comments in the doc plan or in a separate document, during the meeting. Do this note taking yourself — don’t rely on others. Your attendees won’t mind your making notes, as it shows that you care about their feedback. Other note takers don’t have the depth of context that you have, and they may miss important items.
  • After you’ve walked through the sections of the doc plan that you intend to cover, make sure you sit back, relax, and give everyone time to think about the bigger picture. Often the most useful feedback comes at this stage, when people know they’ve seen all that you want to show them, and they can think independently.

After the walkthrough

Update the doc plan to incorporate the feedback that you’ve received. If necessary, change your design to match your new understanding.

Finally, send the doc plan out for review, by email or using whatever channel your organisation uses for this type of review. Make sure you send it to all the people who attended your walkthroughs, as well as to other stakeholders and team members.

%d bloggers like this: