Podcast – Using sequential art/comics in business

In this episode of the Cherryleaf Podcast, we look at using sequential art/comics/graphic novels in business. We discuss:

  • What is a comic?
  • Examples of comics used in a business context
  • Why use a comic?
  • Tools and resources you can use if you have no drawing skills
  • How to structure the story



Cherryleaf creates instructional content that helps people use a product or complete a task. It can stop them getting stuck, frustrated and making mistakes. See the Cherryleaf website for more information.

Transcript of Promoting Technical Communication to the General Public

Below is a transcript of our podcast episode Promoting technical communication to the general public:

Welcome to the Cherryleaf podcast. In this episode, we’re going to look at explaining technical communication, and promoting its value to the wider general public.

Because that’s the question the Institute of Scientific and Technical Communicators (the ISTC) had to address recently. The ISTC is the professional body in United Kingdom for technical communicators.  The role of the ISTC is to improve standards and, of course, to evangelise, to promote technical communication as a career. And Cherryleaf helps support the ISTC. We’re a Business Affiliate of the ISTC, we have someone who contributes the news blog section to their free monthly newsletter, called InfoPlus+, and we also have a member on the ISTC Council contributing to the marketing of the profession.

One of the activities the ISTC carries out is to attend the University of Cambridge careers fair. This is an annual career fair for undergraduates and schoolchildren, and the ISTC has, each year, a stand promoting technical communication and helping the students become aware that there is this profession called technical communicators. And that leads to a question every year: how do you explain technical communication to this type of audience? And in the past there’s been leaflets and flyers explaining what technical communicators do, and the value that technical communication can provide. There’s been a graphic novel explaining the difficulties an organisation can get into with poor communication and how technical communicators can help, and the areas in which they can help.

When it came to discussing what to have on the stand at the University one idea that came up was to use Lego and to build a piece of Lego.  These days if you want to do a model of one of the Star Wars characters or Batman, then typically you’ll find 80  pieces in that pack. And to put it together correctly and accurately, you need the instructions to go through and guide you through doing it.  With so many pieces, it can be very difficult just to wing it and try and make it without any instructions whatsoever.

So Lego is a good metaphor and a good discussion topic: to help understand, to explain technical communication.  That we have a goal. We know what we want to achieve. And with all these different pieces, you need help and guidance to help you get through that, or help the spot where things have gone wrong.

And the Lego documentation is very good. It also gives you an opportunity, if you want to discuss in a little more detail, how Lego have approached this problem. What have they done to make it easier for children from six years upwards to create these models. And within Lego instructions, you have things like:

  • They don’t use words, they tend to use pictures
  • They stick as much as possible to one perspective; one view of the bricks of the model
  • That the diagrams are three-dimensional
  • It’s designed in a format that is small so the pages can be turned by somebody who is only six years old
  • They use colour and shading
  • They document every step, they don’t omit anything

So it can help people appreciate some of the subtleties and finer aspects of how technical documentation is created.

And this issue of promoting the value of technical communication evangelising arises in the other ways in which the ISTC promotes itself, primarily the ISTC website, istc.org dot.uk.

And again, how on a website can you promote technical communication to the general public. And so we came up with the idea could we apply this idea of Lego, and incorporate it into a video, and use that as the way of explaining the value of technical communication and what technical communication is.

So that involves a trip down to the supermarket to buy some Lego, to see what we could get with our pocket money. And for £9 we bought the TIE Striker Micro Fighter, and used that to create a little 90 second video. So, the idea of the video is to show the box and the model that can be created and the parts that come in the box –  all 80 or so different pieces, to show the instructions, and to show what you get at the end. You get your completed TIE Striker Micro Fighter. And we also decided to show what can go wrong if you don’t follow the instructions, by creating a model by not following the instructions.

We decided to create this video in-house at Cherryleaf. There were a number of reasons for doing this. One was if we were to bring in professionals, there wouldn’t necessarily be enough time to get it done before the Cambridge Fair. We wouldn’t really be in a position to give an accurate detailed brief to a set of external professionals on quite what we wanted.  In many ways it was case of experimenting. Having a very rough idea of what this video would contain, but not really knowing what all the things would be or how it look without actually doing it. We have a studio. We have lighting for the e-learning courses that we use so we use. That is a place for recording the video. So we began by showing the box.  Showing the parts in the box. And to highlight that, to have the parts cascade onto a table. To show how many different parts there are.

The next stage was to create the model. And when it came to creating the model, we then discovered that there was a part missing. And it would be very easy to blame Lego and say that the part wasn’t in the pack. But unfortunately, we had video evidence, having recorded these parts cascade down. And that part was actually there, at that point. So, this delayed things overnight, and required somebody to come in with a box of Lego from home to find a suitable part, to replace this missing part.

One of the things when it comes to recording in this way is it is quite different from recording a learning material. You need a camera rather than a laptop camera. We needed really a rostrum camera to film pretty much from the top down. And with a bit of make do and mend, we managed to get around those particular issues.

So we had to find a volunteer to follow through the instructions, work on Lego for or an hour or so to put together this model. We filmed the model. And because we’d been using these parts from this box of Lego bits to fill in as the gap where this missing piece was, this also gave us the opportunity to customise it. So that when it came to creating the alternative version the model that didn’t quite work – because instructions weren’t followed. We were able to adapt this model of the TIE Striker, and make it clearly something completely different. And also stick a pole on it. And to illustrate what can happen if a product isn’t built correctly – by having it shaky and badly traveling through space, this TIE Striker.

To this video, we added a voiceover. Having illustrated the benefits of following instructions and the consequences if there are bad instructions if people don’t follow them correctly, we completed the video by talking about the ISTC what it does, the benefits for professional technical communicators joining the ISTC.  And also for people who are doing technical communication, but this isn’t in their job title. The point that joining the ISTC could help them in their career. So the video was put together. It’s up on YouTube now, and we can listen to the audio track from the video:

“There are lots of times when we want to achieve something but we don’t know exactly how to do it. Technical communication is the term for the information that guides people in this situation to help us reach our goals without the right guidance sometimes things can go wrong technical communication is all around us it can be information written on the product itself

It can be help text for a software application, or guidance text in a dialog screen. It can be a quick reference card in a box, a getting started guide, a technical illustration, even a comic.

So what do you call someone who does technical communication for a job? Well, you’ll see them called technical authors, technical writers, information developers… A simpler term is just technical communicators. And the professional body for people who do technical communication is the Institute of Scientific and Technical Communicators.

if you’d like more information on technical communication and the value you can provide and technical communicators, and the skills that they offer, visit the ISTC’s website istc.org.dot.uk.

And if you do technical communication as part of your job, joining the ISTC could help your career.”

One thing you’ll notice is we didn’t add any background music, what’s sometimes called the audio bed. If you are involved in creating promotional videos, then that’s worth considering.

You can, if you have a budding musician in your organisation, get something composed in that way. In the past, on the Cherryleaf site, we’ve used audio tracks from a company called Melody Loops. And for a few pounds or a few pennies, and in some cases free of charge, you can download loops that can be two minutes long, one minute long, that are musical backgrounds. We decided not to use a background that was the preference from the ISTC Council members

If you do add a musical background, it can have an impact on those who are hearing-impaired. So that’s one aspect of it. Also with a lot of corporate videos, you end up selecting ukulele-based music or American soft rock. And the audio beds can be rather generic in that way. So, the decision was made to not have an audio bed.

We started this episode asking the question, how can we promote technical communication to the general public, to a wider audience? And I hope we’ve shown in this episode that Lego pieces are an effective way of doing that. It’s something that many people are familiar with. Your child and undergraduates or grown-up. In many ways, we’ve all played and used Lego and seen the instructions that come with it. And think of the effect if you’ve lost those instructions and you don’t know how to put it together.

You’ll find the link to the video on YouTube in the show notes. And one final request is if you have the time if you could pop over to Apple iTunes and the page for the Cherryleaf podcast. If you just give us a rating, star rating, or like it, that will help us enormously in promoting this podcast to other people interested in issues around technical communication.

Thank you for listening to this episode.

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 Cherryleaf.com. There’s also a comment section on the podcast hosting platform Cherryleaf.podbean.com. You can share your comments there as well and on Cherryleaf.podbean.com. You’ll also find the show notes.

If you’d like more information on Cherryleaf ourselves, then have a look at our website Cherryleaf.com. 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.

Transcript of Delivering technical documentation via an API

Below is a transcript of our podcast episode Delivering technical documentation via an API:

Welcome to the Cherryleaf podcast. In this episode, we’re going to look at documentation APIs.

In a previous podcast we looked at trends in technical communication, and we were debating whether to include documentation via an API as one of the future trends for 2018 and beyond.

We thought we’d explore it in a standalone episode, which is the episode that we have here. So we’re going to look at: What is a documentation API? Why you might want to use one some examples, and some of the tools and platforms that are currently available.

One of the challenges with this topic is there are actually a lot of content APIs around, and a lot of the information that’s transferred is content.

  • You have APIs for providing weather information: that the weather in a particular city is so many degrees, and it’s windy, or it’s cloudy.
  • And we have APIs for adverts. So there’s an API for Bing, where you can use that to get different adverts embedded onto a particular sites.
  • And there’s also APIs for platforms provided by organizations like the BBC and the Guardian,

And often this information is organized in pairs of data; a key and then a value for that data, stored in a text file, usually in a format called JSON. And in many ways this is what you might have previously called just “data”.

So we need to try and differentiate what we mean by documentation from that type of information. Differentiate the type of information and content that technical communicators provide. The type of information that you would see more in a instructional set of guides than in a weather report.

The definition that we’re going to use, or the focus that we’re going to take, is on the type of information that you might see in a user guide or an online help file, and that essentially is instructional, task based information, or reference, look up, information, and particular information that might be more than just a city and the temperature. So content that might need to be presented in tables, for example.

And again another challenge with this topic that can make it rather confusing is, of course, a lot of this can also be delivered if you wanted to automate it. And that’s one of the reasons why you’d use an API. You could automate it by using a chatbot, where that would be serving up the information, and potentially providing that information using voice rather than text, and we’ve done a podcast on chatbots previously; so we’ll leave that for this episode. Have a listen to our podcast on chatbots. We’ve also got a primer guide to chatbots as well, so do have a look at that.

So why would we want to use an API to deliver documentation? We can use a content management system today to deliver information. It will enable us to deliver it as web pages, as self-contained Help files, as PDFs, and a content management system can personalize content. It can narrow and filter the information to suit different users, individual users.

So what would an API give us over and above what we can use today with the content management system? To answer that question, a good starting point is to go back to what an API is. And in its simplest terms, an API, an application programming interface, is a way that two machines, or two pieces of software, can talk to each other automatically.

The use case or the situation where we might want to use an API is where we want our content to be used by another system. So that may be where there is a system that has a workflow and there is a need to provide the end-users with information and make decisions. A performance support role for the content. A number of examples of this might be that you have Salesforce.com as your platform for supporting end-users, for marketing and selling in your company, and you may have customized and adapted Salesforce to your particular situation; included the different products that you offer, the different prices, different types of customers, and so on, and you might want to provide specific information to your Support people or to your salespeople that can have on the page, as they’re going through a support call or a sales call, information from the instructional content, from the reference content, from what might have been in the past called a user guide.

Another example is one that was mentioned on another podcast, Scriptorium’s podcast, a case study on how they have worked with the American Joint Committee on Cancer. The AJCC provides a manual on cancer staging, related to whether somebody has Stage 1, Stage 2, Stage 3, Stage 4 cancer, and that information is used by providers of medical systems to help doctors make decisions. And the AJCC has converted that content into being an API, so that these providers of healthcare management systems can include this official content on what is defined by different stages and how you would make decisions to classify a patient. Having one of those, they made that information available as an API, so that the software providers can include it in there. And we will include a link to that podcast, that Scriptorium podcast, in the show notes.

Another situation may be that you’re using a platform like SAP, and that you have customized the SAP platform for your particular situation. So that it’s organized by the number of offices, or the number of factories that you have, or again the number of products. And to help somebody that’s perhaps defining the levels of depreciation in different countries for depreciating assets, or making decisions over a stock rotation, there is reference information in your system. Legal information they might need to be aware of company policies. Do’s and don’ts that that could be embedded into the SAP screens from an API.

So a common theme may well be that you want your information embedded into other applications. You might want information that describes different parameters as to when and where you’d make a decision. Issues around safety; it might be rail safety, it might be aircraft safety. Making sure staff conform to certain rules. Those are some scenarios where API delivered content might be useful. How can we use an API to deliver our content? Well, one approach is to use one of the platforms that’s used for content. A platform, for example, like a content API platform. If we’re using voice, we could look at the APIs that Amazon provides. And one of the ways in which Alexa is being used, is to provide instructions and information on recipes, or instructions on how to use a product.

But again we’re we’re veering into chatbots. Let’s move away from that.

Another platform might be the GatherContent API, which will interact with a number of systems. In particular, platforms that provide help desk type information. The team that have developed the ReadTheDoc’s platform for API developer documentation has a platform called EmbedAPI. And this enables you to embed content from your content if it’s on the Readthedocs website. And enables you to embed that content that’s hosted there into other platforms. And this is a way of making sure that’s API related documentation, which is often the type of content that resides on Readthedocs, is always up to date always there in these other applications.

What about platforms within the field of technical documentation more focused on user based instructional content? What do we have in that way?

Well, there are a few, but but not many at this stage. There is Paligo, and Paligo is a content management system in the cloud, and is based on DocBook. The content is structured in that way, and it’s possible to use the Paligo platform and its API, to have your content integrated with some of the most common help desk portals and with Salesforce.com. Mindtouch, which is a popular platform browser-based platform, again for providing help desk information and also user instructional information, that also comes with an API. And you can use the Mindtouch API to extend your product documentation so it’s included throughout the customer journey.

If you’re using Markdown to write your content, your choices are going to be more limited. Because there is this need to have this semantic wrapper around this content, this metadata, to say what information is there is. One platform that can do that, one called Forestry. The API for that is not publicly available, but there is a private API that’s available on request. So that may be worth considering if you want to write only using Markdown.

So that’s a very brief overview. We have these overlaps between other API systems that provide other types of content. We have overlaps with chatbots and voice based information. And it may be that documentation is API won’t really become distinct from those. But there may be, in the future, a need to distinguish like we have between those other forms, and provide our content via an API into other systems. It really depends if your content needs to be used by another system, if you need that situation of one machine talking to another.

We’d welcome your thoughts and your experiences on using documentation based APIs, and other content APIs, where they’ve been applied to technical documentation. So do share your thoughts. We have interviewed people in the past on the podcast, so there may be an opportunity to record some of your thoughts.

If you’d like to contact us, you can email us: info at cheryleaf.com.

If you want to see these show notes, with links to some of the topics that we’ve talked about, some of the products, you’ll find those at cherryleaf.podbean.com.

And if you’d like to know more about Cherryleaf, and our documentation services, the training courses, the recruitment side, and the project side, then you’ll find that on our website Cherryleaf.com.

So this is the last podcast episode for 2017. We wish you a happy New Year, and we’ll be talking to you again by podcast, and through other means, in 2018. Thanks for listening.