Writing software documentation is hard. No joke. Companies typically start with developer-written documentation but quickly realize it’s not a great experience for the users reading it. The typical path out of this situation is to hire a tech writer, who can come at the documentation from a user’s perspective. But recently, I heard a different approach proposed: replace text-based docs with videos, prepared by the engineering team themselves.
That is just wrong.
Video can certainly add value to your text documentation, but it’s not a replacement. It doesn’t solve for the things that make documentation hard, or for the problems caused by developer-written content. Let’s think this through…
Most people find it very difficult to adopt someone else’s point-of-view, and this is an especially big problem for documentation. A programmer who’s been up to their elbows in this code for weeks or months has probably lost perspective. They are going to have a lot of difficulty then explaining it in a way that even an outside developer can understand, let alone a Project Manager or CTO. Incidentally, this is a general problem. Any expert will tend to forget what non-experts don’t know.
The main value-add of a good technical writer is they are able to adopt multiple points of view and then create content tailored for those perspectives.
Asking a developer to give a video tour of their code, presumably after they’ve written it does not solve this problem. You’re still getting an explanation from an insider, and with video this explanation is entirely one-way. Which leads to the next problem…
I’ve seen it claimed that video documentation could even be used for internal communication, to help tech writers better understand the code they’re documenting. Unfortunately, I don’t see the value. What helps me understand better is, for example, being able to sit down with the developer and ask them meaningful questions about their code. Recording a video just means that instead of being able to interrupt and ask questions, I have to sit through the video and let my questions pile up. The information in a video is entirely one-way, linear, and goes at a pace of the developer’s choosing. Actually, this probably deserves its own section!
Written documentation, for all its potential faults, is at least searchable. You can ⌘+F through it, and you can scan it to get quick information quickly. With video, you have to sit through the whole video and hope it has the content you’re looking for. Best case scenario, you can scrub through the video and hope you hear the word(s) you’re looking for.
With written documentation, once you’ve found the relevant bits of text, you can:
- Try running it. Take that REST call and try it out and see what happens.
- Paste it into an email or Slack message and ask someone about it.
- You can use it as the basis for other documentation! A white paper, or a blog post, or a press release.
And when that code changes, when the documentation has to be updated, you can just search through the documentation again, find the bit that’s changed, and go and do your updates! Which brings me to the final major problem with video documentation.
What happens when that 2-hour live coding video is now ever so slightly out of date? Do you record a whole new video? What a waste of time. Do you record a new segment, and then splice it into the original video? That’s a lot more work (and cost) than updating some written docs. Do you record a short, context-free snippet about only the new content and expect people to watch it? Updating written documentation can take seconds, requires no additional resources, and prevents confusion.
I’m assuming the problem space is this: you don’t to rely on a tech writer for docs. You’re dedicated to having your developers write documentation and putting that out into the world. How can you make it work?
A lot of companies hire developers based purely on their technical skills. If you expect your developers to write documentation other people can understand, you need to evaluate communication skills as well. Add documentation as a responsibility in the job posting, talk to your recruiters about it, and make sure it’s part of the interview process. Review written work.
Our mantra at Stormpath is, “If it isn’t documented, it doesn’t exist.”
This means that the work isn’t done until it’s documented. This will solve a lot of your problems. You’ll make documentation part of the project planning and estimation, which means it won’t become a low-quality afterthought thrown together long after the code is released, or never at all.
Developers can write documentation without being in charge of documentation. Someone with distance and perspective can:
- Establish rules for style and consistency, and enforce them. Make sure your docs use consistent language. For instance, one person may call it a “User Profile”, but someone else calls it an “account”. That’s going to cause confusion to a reader.
Read the docs before they go out. Is this content easily understood by anyone other than the author? That should be your first check. Spelling and grammar are also important.
Make sure your team is documenting their work. If you hired a developer with the expectation that they can write documentation, then someone needs to make sure that this is happening!
So, is video documentation the answer? If you want a way to help you engage with your audience, or demo new features, then absolutely it can help. But as a replacement for written documentation, both internal and external, it’s just all wrong.