I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.
Matthew talked about how the concept of a minimum viable product would apply to documentation. The minimum viable product, MVP, is the belief that building software is expensive and risky. So sometimes the best solution is to build the bare bones version first and then rapidly iterate.
You want to test the feasibility of an idea before sinking more resources in to it. Even if you’re just spending your time there’s the opportunity cost of building software. By building as little as possible you can launch faster. Unfortunately this frequently means documentation is cut. This, in some cases, is because product managers don’t understand the value that documentation provides.
You can do early-stage testing with early adopters. However, if your audience is mass-market they may not be the best test audience. Matthew’s example here was, “How many software developers do you know that use Pinterest? What if they used tech-based early adopters as their test audience?”
The product you create must work better than existing solutions. This applies to the product, documentation, and the tools you use to create both. Sometimes printing out a form, filling it out, and faxing it back is easier than dealing with an Adobe browser plugin.
Unfortunately lots of people think of documentation as a safety net for your user experience. This isn’t necessarily a healthy relationship.
Interfaces are, at their base, about manipulating abstractions. Without a strong grasp on that iconography you’re going to have a difficult time using that product. This is a problem, though, that technical writers are well-placed to deal with. They’re frequently in a good place to help understand how users will interpret what you are saying.
One way to help with documenting your product is to pair with new developers as they come on board. You can document the difficult things as they have questions. This lets you save time in the long run as common stumbling blocks are removed and documented. Reference docs, in this sense, are a form of outboard memory. They’re primarily for people who understand how something works and are looking to refresh their memory. While reference docs are key for APIs and other elements they aren’t the best teaching tools.
To write the best teaching doc you need to, on a certain level, forget what it’s like to be an expert user of your tool. Personas can help with this as they help you come at a problem from a given perspective. The how-to document is, Matthew argues, the biggest impact for getting a user from zero to hero. It’s a tried and true documentation format but it works. How-to docs work with user experience design to effectively document the experience of using your product. If the process for doing something is complex to write then it’s likely too complex to use as well.
You can also use your how-to docs to regression test your user experience. When developing software you’re going to break something. Having how-to docs in place helps communicate how the software is supposed to work. You can catch bugs when there’s a deviation from that canonical how-to explanation.
There’s also a way for writers to be proactive in a lean development process. As Matthew put it, what if you thoroughly prototyped your user experience in words first? It’s an author’s equivalent of test-drive-development. Combining that approach with some UX design knowledge gives you the opportunity to truly be a leader.