Transcript of Trends in Technical Communication in 2018 and beyond

Below is a transcript of our podcast episode Trends in Technical Communication in 2018 and beyond:

Welcome to the Cherryleaf podcast. Towards the end of each year, normally on the Cherryleaf Blog, we make predictions for technical communication in the next months and beyond. Because we’ve been doing the podcast, in many ways we’ve been looking at future trends as the year has gone on – through the podcast itself. So, in this podcast, we’re going to look at some of the current trends. Trends that we’ve predicted in the past that have become, or are starting to become, mainstream. And, also, we’ll look at potential future trends. But this year what we’ll do is, we’ll be a bit more ambitious. We’ll look at some more potential trends that we might see in documentation. These ones may have less certainty than some of the predictions we’ve done in previous years.

Our predictions in 2017 were that we would see Docs Like Code and the growth of storing content in repositories like Git. And we did an interview with Anne Gentle who’s written a book on Docs Like Code on a previous podcast. It’s still growing. We’re seeing more of that going through.

Another prediction that we had was that Markdown would break out from being an authoring format for developers and into the mainstream. Well, we have seen some browser-based content management systems introduced for writing documentation based on Markdown. Again, that prediction that trend has come to pass in many ways. However, in terms of a prediction for the future one thing that we may see is that another lightweight language, an alternative to Markdown, may start to grow. And that is AsciiDoc. And AsciiDoc is a lightweight language markup language like Markdown, but it has a basis upon a semantic XML schema called DocBook. And what that means is, it has extra capabilities that you don’t see with Markdown. It gives you the opportunity to mark-up topics semantically. And by doing that, have the ability to filter content for different audiences.

Another prediction we made last year was that technical communicators will use Lean methods when working in an Agile environment. And it’s still early days. I would say however we are seeing more and more presentations on Lean techniques and other ways of doing Agile authoring at conferences.

Another of the predictions from last year was we’ll will see the greater use of the imperative voice: create…open…close… That’s what we mean by the imperative voice. Compared to: opening…closing… , which is the gerund approach that you’d see traditionally. And certainly, that one has been growing more and more over the year.

And we also predicted that the popular Help authoring tools will be able to generate embedded Help and onboarding screens. Well, this one was a wish last year. I think it’s still a wish for future years.

So those were our predictions back in for 2017 and beyond. Let’s look at what we can predict for 2018 and beyond.

So, let’s start off with Every Page is Page One. This is the idea that you have users who search on Google for an answer. They go from Google to a web page and that’s their starting point. That’s their page one. And you need to write your content on the basis that they’ve not read anything prior to going from Google to that particular page. And our prediction is that that technique of Every Page is Page One will grow – and it will be misinterpreted and misunderstood by many people.

So a next prediction is what you might call “left field”, and that is that blockchain, the technology that supports Bitcoin, will be used in the workplace in different situations in addition to having it as a means to support a currency. And that we will see it used within the workflow to do with content and documentation. So the main areas that we’re likely to see this, is within the process of getting contracts and other legal documents approved. And also, within situations relating to the documenting of policies and procedures.

So what do you get with blockchain? You have the ability to commit decisions to a blockchain. You have the ability to verify against a blockchain that what you’ve received hasn’t been changed, hasn’t been interfered with. You can control who can and cannot commit changes to the blockchain. And you can make the process of changing things secure, by using keys.

How can we apply blockchain to documentation? Well, there are situations where you want to prove compliance. You want to have security, and you want to have auditing. And these relate to information security and governance. This can be, for example, to do with contracts between you and a third-party. Typically, what will happen is you’ll send a contract out to somebody to sign, and it may come back, and they might have taken out a clause or added a clause in there. So often, within the process of approving legal contracts, there’s a lot of checking that needs to be done to make sure that nothing’s been slipped in unexpectedly. With blockchain you can identify or prevent those changes from happening. So, within legal documentation, there may need to be a case of who made a change. With the auditing side of things.

But we also have that auditing side with compliance documentation. In a previous podcast, we talked about a situation where IKEA might want to get information from suppliers on the materials that have been used in the furniture that IKEA provides. Information on the amount of formaldehyde, the amount of glue, whether it’s from a sustainable forest. And again with other policies and procedures, you can track when and who made a change to a document at some point. Blockchain is offering a way of minimizing the information overload by making it easier to identify when changes have happened and to approve any changes that go through.

Another prediction for a future trend in technical communication is again one we’ve covered in the podcast before. And that is the application of artificial intelligence and chatbots in technical communication. And we’re now seeing from IBM, from Amazon, from Facebook, from Google, from Microsoft, services which mean that you can take your content, apply it to the platforms they provide, and enable them to start instigating machine learning and to develop intelligent chatbots.

Well, the background noise might give away that I’m in a different location. I am in one of the places we use for meeting people for informal chats, and the Members’ room at the British Museum.

A lot of the development going on in the software sector, at the moment, is in the field of APIs, and that growth in APIs is leading to a number of trends in the documentation field. So having to create documentation aimed at developers rather than the general public. And this may be where we’ve seen the growth of systems like Docs Like Code. We need more input from developers to contribute to the documentation. We need to align it more closely with the help of development and therefore use the tools that they are using.

This is also linked to a general theme covered and mentioned in “Information 4.0” and elsewhere: the single sourcing and the molecular element of content. Breaking things down in that way. But this, of course, has been going offer for many years. This is also leading to the different means by which content is delivered. But I think what’s coming through that’s new is the adding of an additional semantic layer.

But what about the trends we’d like to see in the future? One would be to have the testing of user documentation. Testing that it’s appropriate to the audience, that is what they want. And there has-been very little testing in the past. One of the interesting things with the development of the Government Digital Service in the UK is their underlying philosophy is to test and test the test again. Interestingly, when you talk to them, there is, actually, very little reuse of content across their different documentation sets at this moment in time. Now that may change, that may grow, but it may be that, actually, when it comes to providing almost appropriate information for users, there may not be as many opportunities to reuse content as we think.

So those are our predictions for and beyond. We’d be interested in what you think do share your thoughts on our predictions; which you think we’ve missed, and whether you think we’re right or wrong. You can share your thoughts via info at There’s also a comment section on the podcast hosting platform You can share your comments there as well and on You’ll also find the show notes.

If you’d like more information on Cherryleaf ourselves, then have a look at our website There you’ll find information on our writing services, training courses and consultancy. But apart from that, I just like to thank you for listening to this podcast episode.

Script theory in technical communication

In the latest episode of the 10-Minute Tech Comm podcast, Ryan Weber talks to Kirk St. Amant about script theory and prototypes, as concepts for researching User Experience. They discuss Kirk’s article “Of Scripts and Prototypes: A Two-Part Approach to User Experience Design for International Contexts“, which was published in Intercom and is also available on

Script theory examines patterns of action in particular contexts. It proposes individuals often plan their behaviour in a context based upon what they expect to take place in that context. These factors influence a person’s expectations of usability in each setting.

Script theory could be useful in understanding people’s view and expectations towards technical documentation. It might also help us reframe User Assistance when it is used in different contexts, such as when it is delivered via chatbots. Sometimes, people have prejudices against user guides. These may not be there if the content was delivered in a different context.

Incorporating the Stripe API look and feel into a MadCap Flare project

Back in July, we looked at creating an API documentation portal using MadCap Flare (see also: Example of API documentation portal using MadCap Flare) .

We done some further testing. We’ve created two new examples for  API documentation that had been generated with the Stripe API look and feel and imported into Flare:

To compare the two, here is the standard “Stripe API” left-hand Table of Contents when imported into Flare.

We’ve not made any changes to the default Heading styles from the source files. The stylesheets would needed to be modified to make them consistent with the styles used on the other HTML pages in the project.