Vlogging – the next stage in technical communication

Oh my Vlog magazine coverAnyone with children or teenagers will be aware of the popularity of video bloggers, or vloggers. Their videos on YouTube rack up thousands of hits, and there is even a magazine dedicated to the activity.

Many vloggers provide instructional information, such as makeup tips, so it should be no surprise that some have moved on to more technical subjects, such as Zoella’s guide to Swagger API, and Alfie’s hints’n’tips for Eclipse configuration.

Due to the high high fees they command, partnering with the most popular vloggers is only feasible for large organisations with big budgets, such as Apple, Google and IBM.

For smaller companies, the best option is to create a vlog using their own internal staff. To help those Technical Authors wanting to create a vlog for their content, you’ll find below links to some free background images you can use in your videos, to give that recorded-in-the-bedroom feel. Simply record your instructional video with a “green screen” background, and use the chroma-key feature in Camtasia or Captivate to replace it with one of the vlogging backgrounds below.

The Zeb:

vlog background 1

The Zoe:

Vlog bedroom

The PewPew:

vlogbed3

If you’d like to obtain the complete “technical communication vlog collection pack”, simply contact us via email.

See also:

We welcome you comments

Please share your thoughts below.

Lessons learnt from developing our API documentation course

We’ve written our new training course on documenting APIs, bar the model answers, and it’s now out for review. We’ve learnt a few lessons, and confirmed a few beliefs, whilst developing the course. We thought we’d share them below:

  • Start with the absolute basics. It’s best to assume little or no knowledge of the subject, and start from there. It’s easier to skip or omit those sections, than try to add them in at a later stage.
  • Stick with a single theme for the exercises and examples. One of the challenges we had was to create exercises and examples that take delegates through all the stages of developing API documentation. We decided to base these on an imaginary API for a hospital, and this turned out to be a good choice. It’s meant we can use real world examples from healthcare,  as well as ones we’ve created, during the course.
  • Make the examples visceral. The more you can anchor the exercises into people’s lives and experiences, the more real and meaningful they will be for them.
  • Don’t get sucked into looking at only one tool. There are a number of ways to develop API documentation, and the tools are developing at a rapid pace.
  • Don’t be too ambitious with the exercises.
  • Writers want to write on a training course about documentation, so give them the opportunity to do so.
  • Set realistic expectations regarding coding skills. You can’t teach people how to code in multiple languages in a day, so you need to provide building blocks that they can build upon in the future.

The slide deck now comprises 330 slides, and the test recordings indicate it’s a one day course. We’re still not convinced we have the best title for the course – if you have any suggestions, do let us know.

Should API documentation be more like an application?

Twillio announced this week a new form of documentation for their API. Abraham Maslow once said “If you only have a hammer, you tend to see every problem as a nail.”, and the developers at Twillio have looked at the issue of how to describe their API as something that can requires a more application-like solution. Twillio has developed step-by-step tutorials that provide an annotated walkthrough explaining what each significant chunk of code does.

With Tutorials, we tried to reverse this relationship between text and code. Code shouldn’t illustrate the narrative – code should be the narrative… Each Tutorial is itself a full application you can use as a jumping off point. You can browse the significant files in the Tutorial’s file explorer by clicking the folder in the upper right corner. You can get the app’s full history browsing the commits on GitHub.

This view highlights an attitude towards code examples in API documentation. Are they there to act as tutorials to teach developers how to code? Are they illustrations similar to figures in books? Are they handy timesavers for developers wanting to start using the API?

Twillio’s view seems to be that the code should be, in many ways, self-explanatory. We suspect the tutorials will end up complementing, rather than replacing the API reference documentation.

What do you think?

Presentation on technical writing in Lean and Agile environments

Cherryleaf’s co-founder, Ellis Pratt, will be speaking at the next meeting of the ISTC’s Southern Area Group. The event will be on Tuesday 17th May at The Keep, 29 Castle Street, Guildford, GU1 3UW from 7pm. Ellis will speak on Technical Writing in Lean and Agile environments. He’ll explain how to rise to the challenge of writing user documentation in an Agile environment and how Lean and Agile could be used to manage writing projects.

Doors open at 7pm, and Ellis’s talk will start around 7.30pm. Afterwards there will be the usual opportunity for questions, for serious discussion, or light-hearted chat, depending on your mood and inclination.

The event is free, and open to all, so tell your friends and colleagues! But if you are planning to come, please register on Eventbrite here: https://www.eventbrite.co.uk/e/technical-writing-in-lean-and-agile-environments-tickets-22468971298 and they can let the venue know how much space to reserve for us and how many people are likely to want to order food.

Parking is available in the Tunsgate Multi Storey right next door to the Keep, or the Sydenham Road Multi Storey about 250 yards away, but be aware that some roads in the area are one-way streets, so check your directions carefully.

Should we add an API documentation course to our training roadmap?

One of the factors that influences the development of new training courses is, naturally, the potential level of interest in a  particular course.

If you have any comments on what you’d like to see in a course on planning and writing API documentation, please email us with your thoughts.

Reflections on last week’s mini-conference on documenting APIs

Last Friday, I attended and presented at the Write The Docs mini-conference on documenting APIs, held at the Government Digital Services (GDS) building in Holborn. My presentation was called “What makes Technical Communicators uneasy about API documentation, and what can we do about it?”, and there were a number of questions and comments regarding some of the slides that I felt I should expand on.

1. Are there really so few people with API documentation experience?

I showed the results from searching on LinkedIn for Technical Authors in the UK who have API in their profile, to give a rough indication of the number of people with API documentation writing skills and experience. It’s hard to provide accurate figures because:

  • People writing API documentation are not always called Technical Authors.
  • There’s no Standard Industrial Classification (SIC) code in the UK for Technical Authors, which means there aren’t any official statistics.
  • There are approximately 30 million working people in the UK, and only 19 million of them are on LinkedIn.

However, even if we double the number found in the search results, it’s still a very small pool of suitably qualified people.

2. The difference in the skills required for Technical Authors and API Documentation writers.

A lot of people photographed the slide describing the differences in skills required. In the presentation, I pointed out that the priority of the skills could change, depending on circumstances. It’s not in a fixed order.

The main difference is that API documentation requires a much higher level of knowledge about the subject matter. To create an end user guide for an accountancy package, where you are describing mostly tasks, you don’t necessarily need to know a great deal about accountancy. To create an API guide, where you are describing mostly facts, you need to have a greater understanding of the subject matter.

3. The differences in the readers.

I said that Technical Authors tend to describe technical information to a non-technical audience, whereas API documentation writers tend to describe technical information to a technical audience. Some people challenged this statement. I should have said that Technical Authors tend to describe technical information to a non-technical and a technical audience. I believe it’s true to say that the readers of API documentation are more competent technically, and so there will less explanation of basic concepts in API guides.

The event was excellent, with many very interesting speakers. The GDS is working on developing a design pattern for Gov.uk APIs – for example, for the Local Waste Service Standards Project and for the Companies House API. It’s clearly early days for the GDS, but I suspect, where Gov.uk leads, others will follow.

The return of Clippy?

Are we seeing the the spiritual child of Clippy emerge? Truth Labs’s Stelios Constantinides has written an article on his experiments with conversational UIs.

Conversational user interfaces (CUIs) are a spoken or written way of interacting with a device. CUIs aren’t completely new, but they’re becoming smarter, more natural, and — therefore — more useful.

Here’s where CUIs come in: since users already spend so much time in apps like Slack, Facebook Messenger, and even plain-old email, why not integrate your app inside these platforms?

Microsoft ClippyConstantinides  looks at the design process of creating something that doesn’t come across as a robot, and isn’t as annoying as Microsoft Clippy.

This links in with Ann Rockley’s concept of Intelligent Content: “Content that’s structurally rich and semantically categorized and therefore automatically discoverable, reusable, reconfigurable, and adaptable.”

For conversational user interfaces to work well, they need to be automatically discoverable, adaptable and semantically categorized. Microsoft Clippy wasn’t, which is one of the reasons why it failed in its purpose.

It’s still unclear whether this will lead to content being seen as code, or stored in a semantically rich format and inside a content management system. Whichever way, it’s important to recognize that the conversational language is different from written language. We speak differently from the way we write, and this is reflected in how we use messaging apps and authoring tools. Conversations are typically a one-to-one form of communication.

With Siri, Google Voice and Cortana closed off to most developers, we’re likely to see conversational user interfaces developed as alternatives to these applications.

One school of thought is users will move away from searching using sentences, and, instead,  learn to type commands (they will write command line instructions). In other words, they will begin to think and type more like programmers. This is illustrated in the image below.

Slack command line

I wonder if this might be a bit optimistic. There are many people find Twitter too difficult to use, and I suspect it would take them a long time to adapt to this approach.


This topic is something we cover (albeit briefly) in our Advanced technical writing & new trends in technical communication training course (the next one of which is on the 22nd of March).

See also:

(With thanks to Simon Bostock)

What do you think? Share your thoughts using the comment box below.