On the 10 July 2013, I gave a presentation at Edinburgh Tech Meetup on documentation. The audience was a room full of software engineers – some were freelance, some were managers of small startups, some were students who hadn’t entered industry yet. The video and slides are available on my presentations page. After my presentation, I was contacted by the editor for Communicator, the journal for the Institute of Scientific and Technical Communicators (ISTC), and asked if I would write an article on the topic.
I wrote the following article for the Winter 2013 edition of Communicator.
Reaching out
Not everyone likes writing documentation. Denise Marshall explains to developers how to stop worrying and love the document.
In my experience, it is the rare software developer who enjoys writing documentation. I have become accustomed to looks of bafflement from software developer friends. Their experience is the polar opposite of my own: they find it profoundly frustrating.
One of the regular events that I attend is Edinburgh Tech Meetup. It’s primarily a networking event for freelance software engineers, software startup founders, and many others who are generally interested in computing. One evening every month, the group meets to listen to two presentations and spend several hours in discussion. While I usually find the talks interesting, my primary interest is meeting with other members in the software and technology community. It was in a conversation with a developer at one of these evenings that I realised that documentation is getting a bad name among those who could be its staunchest allies.
“What can I say to my boss to convince him to hire a technical communicator?”
As I conversed with the developer, I heard a story that I’d realised I’d heard several times from different software engineers. There seems to be a level of wishful thinking present in the software world that says that the software product should be obvious enough to the users that documentation simply isn’t necessary. Likewise, the code should be obvious enough to anyone who’s reading the source code that a couple of comments in the source is sufficient to understand how all the sources work together. Of course, most developers are aware that this is a pipe dream.
In reality, documentation needs to be available alongside the product. For the work that I do, my readers often don’t refer to the documentation except in their hour of need, either when the workflow isn’t obvious and they cannot find the solution themselves or when they want confirmation that what they’re about to do is correct. For my documentation to be useful, it needs to be thorough enough that they can find the answer to their question and clear enough that they can understand the solution.
The organisations that these developers work for rely on them to document their work. This makes sense because the developers know what the software is meant to do (they have their formal requirements, at least) and they know how to use it. It follows, then, that it would take the developers little time to write up what they’ve done, because they’re the ones in the best position to know what they’ve done.
But these same developers have deadlines that they must meet to deliver the software and are often too pressed to make time for documentation. With documentation included in the requirement, the organisation’s projects can fall behind. The inevitable cycle would lead to someone in management deciding to hire another developer to take up the slack. The existing developers don’t know how to write documentation and get frustrated that more and more of their time is wasted (their words) on documenting their code, rather than being spent on writing good code. Sadly, the blame is placed on the documentation for putting them behind schedule. To add to the feeling of frustration, the developers I speak to generally feel that they weren’t documenting well, because they didn’t know what they were doing. And the new developer needed to be brought up-to-speed, further slowing the development process. I offered the best advice I could: “Convince your manager to hire a technical communicator. They’d happily do the documentation part of the process.” Then would come the inevitable reply: “My manager says we can’t afford a technical communicator. Could you give me some pointers on how to get started?”
What could help their experience with documentation?
I set about creating a primer on producing documentation for those developers at Edinburgh TechMeetup who had no choice but to provide the documentation because their companies could not take on a technical communicator. I could, at the same time, provide those employers who had never considered hiring a technical communicator with an argument for considering one in the future. I knew that the audience I would have in front of me would see documentation as something unpleasant so I wanted them to know that I knew where they were coming from.
A primer on documentation
I’m fairly certain that any reader of Communicator will know how best to communicate information to their audience – it probably comes as second nature – but, for the uninitiated, it can be a baffling world of text editors, words, and images. I laid down the basics that a non-technical communicator would need to produce a minimum standard of documentation:
- Know your audience. If you know who your audience is, then the style and content of your documentation often becomes obvious. For example, if you are explaining to a developer how to use the different functions of an API, then an API reference guide makes sense. If you want to get new hires up to speed quickly then a wiki with some overview information might be sufficient. Do you need to explain how to use software to groups of pre-literate children? Pictures might be best.
- Create a structure. This can sometimes be hard but I find that, in the absence of a strict template, it’s often made easier by writing each idea into separate topics on notecards. These notecards can then be grouped, arranged, and rearranged until they make the most logical sense. This also encourages topic-based documentation. (I also reassured them that, after they’ve got a basic outline, they can save it as a template to simply fill in the next time they needed it.)
- Find your style. Be Consistent and Be Clear. For example, there are many ways to write ‘email’ (Email, E-mail, email, e-mail, eMail, etc), but as long as you pick one and stick to it, you’ll never have to wonder again which is the correct one. Likewise, phrases such as ‘Enter text into the text field’ should be made consistent (other options might include ‘Type text in the field’, ‘Write text in the box’, and ‘Fill in the text’). If you write the phrases consistently, the perceived quality of the documentation increases and the technical communicator can move more confidently into other areas of the writing.It’s also important to avoid ambiguous language. While it can sometimes be hard to know if your sentences will be misread (that’s where asking someone else to review it is useful), it’s easy to avoid ambiguous words. A list of words that should be avoided can be added to a personal dictionary in your preferred word processor. At the top of my current list are ‘since’ (when you can use ‘because’), ‘once’ (when you can use ‘after’), and ‘appears’ (instead, use ‘opens’ or ‘is displayed’).
- Consider graphics. Graphics should be avoided unless you’re absolutely sure that you need them. This reduces file sizes, reduces translation costs, and means that you don’t need to update them with every small UI change. There are times when graphics are good, such as when you’re drawing a diagram of system architecture and it’s important to consider your audience when deciding the necessity of graphics – some audiences might genuinely require a screenshot of every single page in a Wizard.
And that was it. I tried to keep the rules as simple as possible, in the hope that some of it would stick. If one developer could, at the end, decide who their audience was, organise their ideas, and be consistent throughout, then I knew it was worth it. But I wasn’t quite done yet.
Is it worth hiring a technical communicator?
After explaining to an entire room of developers how to approach technical documentation, I asked them the question that was at the heart of the reason that I delivered the presentation: “Would you rather be writing documentation than coding?” The only people in the room who raised their hands were, like me, technical communicators. Every developer I’ve ever worked with has expressed how much easier we make their lives, because we know how to put all the things they know into words on paper. Unfortunately, many in the audience hadn’t had the opportunity to work with a technical communicator. So I laid it out as succinctly as I could:
Hire a technical communicator and the developers have more time to code. Yes, they still spend time on documentation because they need to explain things to the technical communicator, but it is a very small fraction of time compared to what they would be spending otherwise. In addition to that, the technical communicator would be more efficient because they would know how to write.
Reaching out
The most surprising thing that happened, at the end of the talk, was that a developer approached me and confessed that he didn’t think he was going to like my talk. He’d done documentation before and, like the others I’d spoken to, didn’t like it and didn’t really see much use for it. He told me that he was inspired to start documenting the project he was working on. Another developer told me that he’d never heard of technical communicators and had a friend who would probably love the job and asked if there were any training courses available.
I hope this article has helped you realise that we don’t need to limit our audience to the readers of our documentation.
