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?

Editing and proofreading content with linters

A linter is a software utility that flags “suspicious usage” in software. Although linters are used by developers mostly to write more bug-free code, there are a few utilities emerging that work with documentation. They could be useful if you’re writing Web pages, markdown files or XML files.

Write good checks for passive voice, repeated words, adverbs, weasel words, wordy phrases and unnecessary words, and cliches.

Retext Mapbox Standard is a testing tool that checks for common grammar, sensitivity and simplicity errors.

Hemingway is an application, rather than a utility. You can paste your content into Hemingway for an assessment of its clarity. Hemingway will give your content a readability score and identify sections that are hard to read.

New course – Planning, writing and managing an API documentation project

We’ve started work on a new training course about planning, writing and managing an API documentation project. Primarily aimed at REST APIs, this will help you to organise, plan, author and control your API documentation. This course is aimed mostly at people who are not developers, and no programming experience will be required.

The exercises are based around an imaginary API for hospital management system, as most people are familiar with what a hospital is, and what happens inside.

We have have completed the presentation, bar a few teaks, and we are now developing the course exercises and answers. The slide deck currently runs to 256 slides, which means this will almost certainly be a two day course.

We think this course is probably best suited to being delivered in a classroom. We may also offer it as a live, web-delivered course using webinar software for teams based outside of the UK. We might develop a recorded e-learning course at some point in the future, but it’s not something you’re likely to see for a while.

For more details, see Documentating APIs – training course.

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.