A paraphrased conversation, the other day, between me and a customer of one of my customers:
Me: Are you experienced at working with my customer’s developer APIs?
Them: I always feel like a newbie, because there’s so much stuff. But I always end up finding the docs I’m looking for.
Me: I’m writing the docs.
Them: Well, thanks! :D
Whether you’re writing developer APIs or graphical user interfaces, quality documentation that’s easy to find and use when needed is the best way to turn customers from novices who find the complexity offputting, to novices who know they’ll be able to tackle whatever’s coming their way.
Quality documentation is also useful for improving the quality of the software itself.
Docs-driven development
If you already know about test-driven development, you know that a benefit of TDD as a design tool is that it encourages you to think about your code from the perspective of how it will be used. Rather than implementing an algorithm then exposing an API that you hope will be useful, you design the API that helps solve the problem then implement an algorithm to support the use of that API.
Documentation is another tool for encouraging empathy in design. For every point you have to explain, you get to ask:
-
“why do I have to explain this?”
-
“Is there another way to design this such that I don’t need to tell people about this detail?”
-
“Is the thing that I’m telling people how to do, the thing that they would expect to want to do?”
Dev-driven documentation
The questions listed above can be most effectively answered if documentation is part of your iterative cycle of continuous improvement. Documentation can inform design and development, by pointing out cumbersome or difficult parts of the implementation. Development can inform documentation, by showing where the complexity lies and how to deal with it.
Documentation interacts with other activities, too. Test plans should ensure that they cover examples or walkthroughs from the documentation, so that you know the examples you’re giving to your customers actually work. Documenters should collaborate with testers to ensure a shared understanding of what the software is aiming to achieve.
Documents like API specifications, user manuals, or walkthrough videos should be versioned and built alongside the corresponding versions of the software.
Working software over comprehensive documentation
Throughout these activities, the point is not to generate documentation for its own sake. One office I worked in had a shelf containing several feet of documentation for a UNIX system that I never opened: the online documentation and a couple of cookbook-style books were sufficient.
The reason for putting effort into your software’s documentation is that this effort yields improvements in the software. A more empathetic design, a better-tested implementation, and more confident customers are all steps on the path to higher-quality software, easier and faster. And of course, the Labrary can help you with that.
