I recently attended a presentation entitled “Technical Writing…. for Developers.” The topic caught my eye because technical writing, well let’s be honest, communication in general, is not what developers are known for. And that’s too bad, because ultimately the value of any particular technology is directly related to the value that it brings to the lives of humans.
Whoa, that just got real. Take a second to consider that.
Would it be a stretch to suggest that the better we developers are able to communicate with people, the more valuable our software will be? Well, do communication skills help for requirements gathering? How about for getting feedback on a wire frame? How about for general approachability, when a client thinks of a change that would really add value, but decides not to share it because of how we might react? Or what about empathy, which we use to give context to the descriptions, explanations and feedback we get? The Agile Manifesto agrees–it values customer collaboration over contract negotiation (referring to, among other things, scope development), and encourages frequent delivery of working software for frequent feedback. It also states that “Business people and developers must work together daily throughout the project.”
Bringing us back to the topic, I’m going to assume you’re on board with the idea that better communication makes better software. (If not, let us know in the comments.) And since documentation is just a form of communication, better documentation makes better software too.
Perhaps David Krings, the presenter, noticed this paradox of the people in the best place to document their software, and their general writing skills, that made him so passionate about the topic. His talk (slides here) covered the A to Z of technical writing. I got a lot out of it, and I’d like to share some of his key ideas with you.
Types of Documentation
Before we dive in to the details, let’s look at a few common forms of documentation that David highlighted:
- Comments in code: Yes, commenting your code does count as documentation. But they’re insufficient for anything but the simplest software, and, they aren’t useful for non-developers. Commenting your code is a great way to explain how the software accomplishes particular tasks to other developers, but it does nothing to answer the higher-level question “What does it do?”
- Technical bulletins: Short and to the point, a technical bulletin is a quick way to document a problem encountered and the steps taken to resolve it. They come in handy as quick references for customer support people. They’re also useful for recurring issues that are particularly onerous or difficult to pin down.
- Test plans: A test plan documents a single test. It describes what was tested (including the approach, process, and expected result), and the result. By documenting an entire set of test plans, you create a library of tests that define the complete and correct functionality of the software. This would be great to hand off to your QA team!
- Functional specifications: Functional specifications are a formal and detailed description of a system from a user, peripheral, and integrating systems point of view. It does not contain implementation details (unless they are actually requirements). In the waterfall model and other models of software development that are resistant to change, functional specifications are often used to solicit fixed-price bids.
- Technical specifications: Complementary to the functional specifications, technical specifications focus on the actual (or intended) implementation of the system.
The rest of this article will focus on documenting projects which don’t have specific documentation requirements, or where clients may not understand or appreciate the value of having any documentation for the project you’re building for them. For more information the more formal documentation types listed above, please consult your local search engine.
What good is documentation?
Project documentation comes in handy for a few reasons!
- Creating institutional memory: Often, key bits of information that are obvious to the developers actively working on a project are forgotten with a few weeks of moving on to the next challenge. Writing those ideas down will be useful not only to those same developers later on, but also as a project introduction for developers who are new to the project.
- Reducing bus factor: A bit morbid, but very important–a software project’s bus factor is the smallest number of people who could get hit by a bus before key project knowledge is gone, immediately jeopardizing the project’s ongoing viability. By writing those key bits down, the project can live on given any suitably qualified developer and some time to read.
- Reducing risk and total cost of ownership: Consider the scenario where a developer builds a custom application for a client, and then moves away. After two years, the client wants to add features to that system, but the original developer has a new job and no time to build those features. So the client creates an RFP and puts it out to the market asking for fixed-price bids. Companies considering that work will need to first familiarize themselves with the system’s architecture and implementation before they could estimate the level of effort required to carry out the changes. That unknown–of how long it will take to learn enough of the system to cleanly make the changes–represents a risk to bidders, and translates to inflated prices for the client. However, if the project’s documentation has enough of the needed information, the client could simply attach it to the RFP and expect to receive more competitive bids.
What makes documentation good?
Purpose
We start with purpose because it is the thing that drives the entire documentation process. Once you know the purpose of the documentation you’re writing, you’ll be able to answer your own questions in terms of knowing what to document, the appropriate level of detail, appropriate formats to use, and the language requirements (business vs technical). Without knowing the purpose, you’ll just be guessing.
If you’ve been tasked to document your project, but you’re not sure where to start, try this: imagine that all the key developers have disappeared, and someone new with similar core skills is suddenly put in charge of ongoing development. Your documentation will be all the information they’ll ever be given about the project. What do you want them to know?
Audience
Closely tied in with purpose is audience. Communication must be tailored to who’s receiving it. Would you talk with sales people and developers using the same terms? Would you provide junior developers and senior architects the same level of implementation detail? Would you give your 10-year-old the same instructions to use your system as you would a co-developer?
Communication is most effective when it completely yet succinctly transmits the message you’re trying to send. But finding the right balance can be hard. In order to be most effective, you have to know what the receiver already knows, so you can simply build on it.
Accessibility
We haven’t said it plainly yet, but documentation is meant to be read by people. As such, it needs to be accessible! It needs to be easy to find, open, browse and read. As you read the below considerations, consider what’s best for your project by considering each aspect with respect to the audience and purpose of the documentation you’re creating.
Format
Paper, digital or both? Documentation in the recent past has undergone a dramatic shift from the linear “printed-out volume” format to systems containing clusters of information with links between relevant pieces. For printable document formats, PDF is very accessible in today’s world. Microsoft Word is also a popular format, but tends to be challenging to work with for larger documents. For more modern formats, HTML offers unlimited options, for example a Wiki, or as the output of several purpose-built Help Authoring Tools (HATs). Additionally, CHM is the de-facto standard for Windows applications.
Readability
In short, documentation should be well-written. The structure and style should flow easily, establishing and following a narrative throughout. Good structure can make documentation usable either from start to finish, or, as a quick reference. Good style will make reading the documentation easy, despite the often technical concepts that it needs to present.
But I’m a Developer, not a Writer!
Good writing isn’t something that comes naturally to most developers. Speaking from personal experience, I grew up as a child interested in Math and Science; reading and writing were not my strong suits. Although I had to write a lot in school, it wasn’t until my sophomore year in college that I felt that I understood what good writing was. If you’re in this boat, here’s a simple tip: read what you write. After you write a sentence, paragraph, or section, read it back to yourself. While you’re doing so, imagine that you’re actually speaking to your intended audience. Is the information you’re presenting organized well? Are you explaining concepts in a way that the person can understand? Do your sentences flow together, or do they seem like a stack of pick-up sticks? If not, change it to make it easier for the “listener” to receive. The more you read your own writing, you’ll develop your internal voice that will make not only writing easier, but speaking as well. You’ll start to pick up on your weaknesses, and you’ll improve on them. As a final note, becoming a better writer doesn’t happen overnight, so keep trying, and don’t give up.
OK, but what should I document?
This is a great question, and likely why you’re reading this. What do I do? I take my own advice–I assume the audience is a developer with similar skills to myself, and I try to introduce that person to the project through writing. I lean back in my chair, close my eyes and try to come up with all possible scenarios where having something written down would make something much easier. IBM’s ideating commercial is a pretty good analogy. By anticipating how the documentation would be used, I’d then be able to determine what I should put in it. I will freely admit that this method is not efficient. However, I’ve been able to create some very useful documentation.
David’s presentation adds some structure to my day dreaming strategy by suggesting three categories of documentable topics:
- Concepts: Starting from your audience’s expected knowledge and skills, introduce any new business- or project-specific concepts.
- Tasks: Document any tasks or workflows that are required for the project. In my experience, I use several workflows during development for a project, but within a few weeks after the project is completed, I forget the details of these workflows. You should document each task/workflow step by step, to a level that’s appropriate for your audience.
- References: In addition to the Concepts and Tasks, what else might your audience need to know to become self-sufficient on the project?
While these categories do provide a bit of structure for the ideation process, it’s still inefficient.
One idea I have is to keep a list of topics that should be documented during active development. This will result in a great leap forward once you’re ready to tackle the documentation. And, it avoids the inefficiencies that result from documenting something before the client change it.
So that I don’t leave you completely empty handed, here’s a list of topics that I usually hit on in project documentation. You can use this as a basis for your project:
- The purpose and intended audience – make it clear why, and for whom, the documentation is being created. If your audience should have specialized or subject-area knowledge before reading, state those assumptions here.
- The environment(s) in which the system run(s)
- An overview of system components and architecture. High-level details, the purpose, and integration details between components. Components include any bit of software or hardware required to make the project work. Servers, operating systems, web server type, version and modules, required libraries and versions, database server.
- C-T-R from above: concepts, tasks and references
- Framework specific:
- Links to (or copies of) the framework documentation
- Customizations to the framework, or custom extensions developed for the framework. High level: the context and purpose of each customization.
Unless otherwise required, keep it fairly high-level. Let the low-level details be discovered by reading the code itself.
Was it useful? Anything to add?
Documentation is not a sexy topic. But, the value provided by good documentation is unquestionable. I’ve been in positions where I’ve been grateful to previous developers (myself included) for creating good documentation, and I’ve also been in positions of wishing someone had taken the time to write down some basic project information that could have made my life much easier.
I hope this write-up was useful for you. Please share any tips you might have in the comments!