Ryan McDonough

Informal Documentation In The Remote Working Age

Informal documentation for the remote working age

Most documentation is really quite informal in work places, sure there are user guides for software that have been bought but realistically no-one reads those, it’s all passed on to you by the people around you. You’d lean over and go “How do I export the data” or “Why is this button greyed out?” to someone who has used it before, then next time you’d be the person who knew - but then y’know COVID arrived and the concept of leaning over disspeared overnight.

We lost the ability to lean over over when people didn’t look too busy, but now leaning in means a message and a video call, with some screen sharing and what was maybe a 2 minute chat becomes 10 minutes and maybe more with a backlog of questions you’ve wanted to ask but didn’t want to interupt them before.

So how do we make it better?

Well in the past I’d started recording my screen and turning them into GIFs for use in online user guides (rather than 15 screenshots each covering a click and a button press each) to show how to change an image or replace the content of a page - and those worked quite well for people, they were impressed as it felt more like they were watching me do an action, but still it involved a fair amount of text, which sometimes had tangents in them to explain why it did what it did.

GIFs are good but videos are better

I stumbled upon a tool called Loom which for free would allow you to record upto 5 minutes of video for free and be able to narrate with your microphone and do some minimal editting. Another nice feature is you are able to record your webcam as well and place yourself into the video.

The benefits of a video over the say written documentation or creating GIFs is you can quite quickly explain complex processes visually and provide the context inline, in time with the action you are doing - by keeping them short you can focus on a small task that you get queried about regularly and 95% of the time when someone asks you about it you can send the video and that will deal with it.

Now the videos themselves don’t have to be super polished, they can a bit rough with ‘erms’ and ‘let’s wait for this to load…’ - you don’t need to edit out loading screens, or when you say a word wrong, treat it like someone has leaned over and asked you “How do I add this to the page?”

What are some good use cases for this?

At AG we’ve pushed the HighQ platform to it’s limits which sometimes requires including references to JS libraries we’ve written, adding some JSON to pages and extra markup to display timelines, maps, enhanced tables or even full platforms on top of HighQ. We also have a rather large team and secondees with differing levels of understanding of code, so the ability to record a video showing where to add code, how to configure the addons we’ve made and then show how it looks when it’s working is really invaluable to the team.

Example loom clip

Really anything that you used to (or still do) get asked frequently that can be shown in 5 minutes or less is worth doing, remember if something is a bigger task then split it up into chunks so that people can pick aspects of the process as and when they need it, for example:

Got an example?

“How do I get those awesome graphs that you make for the board report each month?”

Now this could be a 20+ minute proccess, you might need to logon to a platform, export all the data which could take 3 minutes to get to the export buttons, then 15 minutes to run and download and then 5 minutes to take the data and create the graphs from it.

Ideally you’d split the videos into:

Obviously you don’t need a video showing you twiddling your thumbs for 15 minutes as the data is exported, much in the same way that if you were at your desk you’d go “So we do this to export the data, then it’s going to take a little while so I’ll come back in 10/15 minutes when it’s done.”

Go do it

So yeah, get Loom or CloudApp or Camtasia or Snagit or whatever and give recording your screen a try.