Adapting to change in technical communication

Technical Authors work in a profession where they must be able to adapt to changes in the technology sector. Often, the changes relate to the outputs they need to create or the authoring tools they use, and most Technical Authors adapt quite easily to the new situations.

However, sometimes there are also changes to writing styles or the type of subject matter, and these can take a little while to get used to.

One significant development has been with the growth in Web-based, Software as a Service applications. In this environment, the User Assistance often fulfils a pre-sales and a training function, as well as providing the help when users get stuck. We’re working on a project at the moment where the writers have had to include this additional type of information, going against their natural inclination to be as succinct as possible. This has involved providing information on why you should use a particular feature, as well how to use it. For the writers, this have meant they’ve needed to gain a better understanding of the context in which the application is used, and deeper understanding of the users and their working day.

The other area that can cause challenges is writing API documentation. This is often written using different authoring tools than usual, and it often requires the writing of more factual, reference information. This can mean the writers need to have some understanding of the programming languages used to create an application, and be able to write for a more technical audience.

These differences is something I’ll be discussing in depth at the free Write the Docs London all day mini-conference on Friday, 4th March. In Aye, Aye, API – What makes Technical Communicators uneasy about API documentation, and what can we do about it?, we’ll look at the challenges mainstream Technical Authors face when writing API documentation.

If you have any insights or thoughts regarding the differences between writing end-user documentation and API documentation, please share them via the comments box below.

Ellis to speak at the University of East London

Cherryleaf’s Ellis Pratt will participating in a panel event that forms part of the University of East London’s Freelance Week. The panel members will be speaking about their experiences and offering advice and tips to current students thinking about freelancing.

The event is on Thursday 18th February at the university’s Docklands Campus.

UEL logoKnowledge dock logo

Our next advanced technical writing training course will be on 22nd March

We’ve just scheduled another of our Advanced technical writing & new trends in technical communication training courses.

“Discover the advanced new writing styles emerging in technical communication by attending Cherryleaf’s popular training course. Don’t get left behind: past clients include technical communicators from Citrix, GE, IBM UK, Lloyds Banking Group, Sage plc, Schlumberger, Tekla and Visa International.”

It will be held on 22nd March, in central London.

Summary of the findings from our 2016 technical communications survey

We asked Technical Authors to complete a survey into the issues and challenges they face in 2016 and beyond. There were four main themes that stood out:

  1. Issues around working in an Agile environment.
  2. A need to develop skills in creating training screencasts. This included how to use tools, structuring and presenting content, and the ideal length of each video.
  3. Improving the status of Technical Authors and the Technical Publications department in the organisation. This topic has come up in previous surveys.
  4. Developing skills in using DITA.

We’ve looked at Agile recently, and we’ll revisit the other topics in the upcoming months.

Thanks to everyone who took part in the survey.

How to create online Help topics that are editable by clients

In the Agile Technical Writers forum on LinkedIn, one of its members posted this question:

“I need to create an contextual online help for an complex web tool (ok, that´s not that hard). The customer must be able to add some specific job instructions to this online help by himself. The customer part must not be overridden when the online help is updated.”

LinkedIn’s forums provide limited functionality for long replies, so I thought I’d answer the question in more depth on our blog.

There are three main approaches you can take:

  1. Transclusion
  2. Appending content to the bottom of a page
  3. Embedding empty placeholder topics within topics (which the client can use to add content)

You can also simply link to an external topic. However, in this case, they wanted the user content to appear with the official content.


In the DITA authoring standard, transclusion is called content referencing (or conref for short). It enables you to insert information from one topic into another. This means you can add customised content to a topic without having to make any changes to that target topic. You specify how the information is pushed into the existing topic: Insert the information just before an element;  insert the information just after an element; or replace the information contained in an element. One of its strengths is, if you are adding new items to a list of steps, the list will renumber automatically.

Here is an illustration from our DITA training course:

conref example

The downside is writers need to be familiar with DITA, or be given a template to use.

Appending content to the bottom of a page

A common approach is to enable users to add comments and additional information at the bottom of each topic. This is the approach taken by tools such as Confluence, Mindtouch and MadCap Pulse.

madcap pulse main screen

This can work well. However, the information can be missed by it being at the bottom of the page, and if there are too many comments.

Embedding empty placeholder topics within topics

Another approach is to have empty topics within each topic. The two topics can be concatenated (joined) together to form a single topic. The client can add any client-specific content into the empty placeholder topic, so they don’t need to touch the topic containing the official content. This is sometimes called embedding topics within topics.

Here is an example of how local branch information is added to official documentation on fire safety procedures:

embedded topic example

The advantage of this approach is that it can be done with simpler authoring tools than DITA (like markdown). The disadvantage is that you may not be able to preview the final topic (to do that, you’ll need to generate the whole document), and it won’t work as well for inserting content into numbered lists.

Do you use a different method?

Please share your thoughts below.

Being Agile in technical documentation – Part three

Two years ago, we wrote a number of posts, and an Adobe-sponsored whitepaper, on Agile and its effects on technical communication. This topic was picked by others, including Sarah O’Keefe and Mattias Sander, who made further suggestions. We thought it was time to revisit this topic, and expand on some of the issues raised.

In Part one, we looked at Agile and the Lean method’s principles of maximising value and minimising waste. In Part two, we looked at how we can minimise waste in the document production process. Here in Part three, we look at practical impact on writing. Agile creates a number of challenges for technical communicators, and this means they need to adapt their working methods in order to work efficiently.

Overall philosophy

From the previous posts, we can get a understanding of the underlying principles of Agile and Lean. These include establishing a rhythm of working continously on activities that add value. Don’t stop and start; don’t batch; keep measuring and checking. The challenge for technical communicators is how to fit into this pattern of work.

Measuring the value and the wastes

Lean and Agile place great emphasis on measuring the value of the work created and the production process itself. Measuring, and identifying “the value stream”, highlights the steps in the process that do not add any value: waste by overburden and waiting, waste caused by rework, waste caused by excessive checking, and so on.

Agile makes the assumption that the waste of creating content describing features or processes that are dropped before release is so great that teams should take a “document late” approach. If you measure your time, this can be tested to see if it’s true. It might be that more time is wasted by trying to work with little available time, or having to wait for input. Many development teams are surprised by how much time and money is wasted once they’ve been made aware of it.

Measuring the value to the user is much harder for technical communicators to measure. For example, you can’t tell how often someone uses a PDF manual. Often, they don’t do any measurement at all. This is a mistake. Usability testing, even if it is on a limited scale, and using people dragged off the street or from the staff canteen, can provide very useful information on what’s not adding value.

Working with sprints and kanban

It’s not always possible for technical communicators to complete their work in a two week window, so some work “a sprint behind”, starting work once a product iteration has finished. Other teams run consolidation sprints, where a sprint just focuses on outstanding tasks such as user documentation.

It partly depends on the team’s definition of “done”. Lean and Agile bring issues to the surface and should force teams to address them. If documentation is part of the definition of what needs to be done (and it should be), the team needs to ensure the documentation work is completed.

Whatever approach is taken, it’s important the task of creating user documentation is on the kanban board, so that sufficient attention and resource is given to the task.

Writing Agile-ly

Just-in-time authoring

One piece flow can also relate to topic-based authoring. Many Technical Authors already create their content in small pieces, topics, that can be used across different documents and media. Conditional build tags enable them to create filtered content, and content created with a particular audience in mind.

Some also use just-in-time publishing to assemble and generate documents or Web pages each time a users requests information. They also use user-defined variables to store static global information that can be used repeatedly in projects, making information portable and simple to update.

However, reviews of drafts are often issued in batches, and there may be a need to look at how this task can be spread more evenly.

An iterative publication of content?

If you have different types of users, you could publish content iteratively. This might mean, in a startup company, you write information for early adopters only at initial release, and update the documentation for less able users when the product is adopted by a wider audience.

Rather than a single major release, information could be published incrementally. That leads to a new challenge for technical communicators: knowing which parts to document and which to leave out.

Tools everyone can use

With Lean and Agile, issues that are forced to the surface are usually addressed by people swarming around the problem. With technical documentation, this can be difficult as Technical Authors tend to use tools that only they understand.

Ideally, you would have an authoring system that enables other team members to lend a hand, if required. You may need a system than can support content created by developers in a tool they know, such as Word or Markdown, or have a multi-user authoring tool that’s easy enough for occasional users.

Adopting one-piece flow could mean creating a flow that fits into the developers’ workflow. For example, it might mean using their tools, such as Git, to synchronise the development of documentation with the development of the product itself.

Communication and Scrums

Another challenge for technical communicators is that changes to the product are often communicated verbally at daily scrums. If the technical communicator isn’t at the scrum, their could be wasting time describing the wrong feature.

It’s not always possible to attend every meeting. Digital recorders can help. If the meeting is recorded on a digital recorder, the technical communicator could listen back to it later in the day. If they replay the recording at twice the normal speed, it can be reviewed quickly.

Managing variations in demand

Having an efficient system makes you more sensitive to variations in demand.

At Toyota, they address variations in demand in a number of ways. They keep the component suppliers informed of any changes, and they have many of the component suppliers located on site. To deal with changes with workload in technical communication, you can do similar things. You can establish protocols with technical authoring companies, such as Cherryleaf, to provide additional resource when it’s needed.

The development teams also needs to understand the impact of variations in demand. Ideally, the Technical Authors have some time to plan, and/or the variation can be smoothed out.

We need to understand variations in demands from end users. We need to be able to respond quickly to changes in customers’ needs, and have the ability to quickly reconfigure content to respond rapidly to any late changes to the delivered product’s functionality. Again, topic-based authoring and measuring can help.


Technical Authors can adapt to working with Agile teams, and they can work in an Agile way themselves. User documentation isn’t something that was addressed in the original Agile manifesto, and technical communicators need to fill in that gap.

We need to set up a rhythm and a way of working collaboratively. This means being on the kanban boards, collaborative authoring, one piece flow, working with the developers’ own workflow, considering the definition of “Done”, and measuring more than we’ve done before.

Please share your thoughts and experiences

Please use the comments box below.

Being Agile in technical documentation – Part two

Two years ago, we wrote a number of posts, and an Adobe-sponsored whitepaper, on Agile and its effects on technical communication. This topic was picked by others, including Sarah O’Keefe and Mattias Sander, who made further suggestions. We thought it was time to revisit this topic, and expand on some of the issues raised.

In Part one, we looked at Agile and the Lean method’s principles of maximising value and minimising waste. Here in Part two, we look at how we can minimise waste in the document production process.

Removing waste from user’s interaction with the product

Let’s briefly touch on value and waste during the use of the product by the user.

User Assistance can contribute to the user being less “wasteful” when they’re using the product: minimising the time having to stop when they get stuck, or having to rework things to fix mistakes. This means you need to provide the right information at the right time, in the right place, and in the right format.

It needs to provide the required information to the reader as fast as possible. In practice, this can mean having the Help embedded in the application itself. It might also mean creating different documents to suit different audiences, or even personalised content. It also implies User Assistance needs to be as short as possible, but not shorter.

This also means you’ll need to carry out some usability testing of the content and perhaps even A/B testing. You have to test to check what you’re producing is what gives value to users.

Removing waste from user documentation process

Let’s look at how we could apply Lean principles to writing technical documentation in an Agile environment.

Is it needed?

The Lean approach can help us identify which parts to document, and which to leave out. Under Lean, you should only document what customers tell you is absolutely necessary. Only information that adds value to the user, or increases their productivity, should be included. If the information isn’t needed by anyone, we shouldn’t write it (unless we have to do it for legal or other reasons).

By going through a design process of empathy, defining needs, generating ideas, prototyping and testing, we can identify the best way to solve a specific problem. In practice, User Assistance (in other words, the online Help and user documentation) should be considered part of the product design, and included in the initial design planning, rather than being left to the end. This requires a change in product planning thinking, as documentation is often treated as an afterthought, pushed to the end of the development process.

In an Agile development process, designers will create Use Cases for each feature, and technical communicators can do something similar. Use Cases can be used in the planning of User Assistance to identify who will use it (the audience), what value it will provide (or what problem it will solve), and when they will use it.

Load levelling

In addition to the waste of “non-value adding work”, in our simplified description of Lean there are also wastes of “overburden” and “unevenness”. These relate to having too much work to do in the timescales allowed, and having to stop and wait for something you need in order to carry on working. Instead, our goal is to have a consistent, productive rhythm to our work.

For technical communicators, this “overburden” and “unevenness” could be waiting for reviews, waiting for edits, waiting for work, or waiting for approvals. It can also mean wasting time having to switch tools or stop and start different tasks. If we can measure these wastes, we can justify the need to change working practices.

Levelling allows a consistent workflow, which makes it possible to set standards and identify abnormalities. The Lean methodology contains a number of techniques for smoothing out a work schedule, such as a triage approach to prioritising new work requests. One of the key ways we can level the technical writing workload is simply to start the project earlier. The benefits from avoiding having to stop and start, or rush things at the end, may outweigh any waste from having to go back and amend some of the content written at the start of the project.

One-piece flow

Related to load levelling is continuous, or one-piece, flow. W. Edwards Deming proved in the 1950s that implementing a continuous flow system, instead of working in batches, can have a significant impact on improving quality and reducing throughput time.

A continuous flow system works like serving people food from a counter. Customers move forward, picking up their stater, main course and pudding as they go down the line. When a serving station runs out of food, there should be a new tray of supplies ready to replenish it just in time to serve the next customer. People only work on one piece at a time and only one piece of work moves from one stage to the next.

Deming proved one-piece flow results in fewer bottlenecks, less waiting and faster throughput. You pull work from the previous step when you have available resources. It also means that mistakes appear earlier. As items are pulled one piece at a time, you should have one only faulty item to deal with, rather than a large batch of defects. If you fix the problem, identifying what caused it, it goes away before it can escalate.

One example of technical communicators working in batches is when they send out drafts of whole manuals to reviewers. One piece flow could mean passing on content for review in smaller pieces – perhaps even issuing content for review on a daily basis, making it an integral part of the product development process.


One of the tools used in both Lean and Agile projects is a Kanban board. This is a visual representation of the pieces flowing through the process. It can help the team identify any problems, and control and regulate the amount of new tasks given to the team. It can be the case that no new work is added to the board until a current work piece is defined as “done”.

One approach is to include the technical writing task in the project Kanban board. This could mean if there are problems with creating documentation, these are brought to the surface for fixing there and then.

Alerting and fixing any problems early

The philosophy of both Lean and Agile is to bring problems and defects to the front, and force people to confront them and fix the immediate and underlying problems.

Within Lean, and often in Agile, when a problem or issue is identified, everyone is empowered to stop the process, and swarm around the problem to solve it immediately. So could a technical communicator have the right to flag to stop the process? Would a development team be willing to face up to the sheer amount of documentation and work with the technical communicator to tackle the problem? The answer should be yes, but it would depend on how closely the team adheres to Agile principles. For this to happen, the team needs to have an authoring system that enables non-professional technical communicators (such as developers) to be able to contribute content.

Dealing with variations in project plans

Technical communicators need to avoid having to pull the emergency cord, and this means they need to be able to deal with some of the variations that can arise as projects change over time.

In Part three

In Part three of this series, we’ll look at how we can modify our writing process and tools so we can implement these approaches into how we work.