Technical writers bring skills to your development team that improve product design and facilitate communication within your team. Involve your writer(s) while you’re still nailing down the details of the specification, and your whole project will go better, from development through market acceptance and customer feedback.
Here are a few of the things a good technical writer will bring to your group:
Clear, complete specifications
Your tech writers are masters of clear, well-organized, unambiguous text. So have them write up the product specifications! Your whole project will benefit.
Here are some criteria for your specs:
- Every stakeholder can find the information they need.
Your writer can produce the specs in the format that works best for your organization, whether it’s an in-house Help system, a database system, an indexed collection of documents in SharePoint, or an advanced mind-mapping system like the team version of TheBrain or Mindjet.
- Every stakeholder can understand the information they find.
Project management, developers, testers, marketing, and upper management all need different kinds of information from your specs. Your writer can write and organize the information so that the details are as technical as they need to be, and the more general information is accessible to a wider audience.
- Specs are easy to maintain.
Your specs may change over the course of the project due to market pressures, customer requests, and unforeseen technical issues. Your specs need to be up to date, and if possible you should preserve the record of what changed and why. Work with your writer or writing team to decide who will be in charge of changes to the spec, since that affects the choice of framework for the spec.
- Specs are unambiguous.
Tech writers are trained to spot and avoid ambiguities in the documents they produce. In the process of producing your specs, they’ll encounter and question ambiguities nobody else was in a position to notice. That can save you frustration, re-work, and missed deadlines later on.
Successful collaboration requires a common vocabulary. If a term means slightly different things to different people, they may produce slightly different results. That could derail your build integrations. It could mean that upper management is expecting something other than what you are building. It can mean that the marketing team is misinforming your customers.
Or, your dev, test, and product support teams may be using terms that will be confusing or worse to your customers. That can make support and troubleshooting unnecessarily cumbersome.
A glossary can insure that everyone in the company is using the same definitions for features and controls. You avoid confusion within teams, between teams, and with your customers. Tech writers (and especially technical editors) are great at hammering out terminology that will work for everyone. They then document it and make it part of your teams’ everyday language.
Relentless customer focus
Your dev team must focus on the technology. Because writers have a little distance from the nitty-gritty of coding, they stay focused on the customer, and that view point in your dev meetings will result in a more marketable product.
I’ve been in plenty of dev meetings where several possible solutions to an issue are being discussed: Do we change the code so this is done in one step? in three steps? Do we leave it as it is, and just document the behavior? As the tech writer, I can say “This will be trivial to document; don’t bother to change it on that account” or “Option A would feel really clumsy to the user.” Or even “Keep it to one step if you can – they’ll be doing this twenty times a day and we want to make it easy.”
Tech writers have a whole set of skills that you can use in your project. They can help you set up your information systems. They’ll add a level of integration to your team’s efforts. They can write your UI text, and review your UI for ease of use. They can coordinate with your marketing team to send a consistent message to your customer base.
Bring your tech writers in early. Integrate them into your dev and test team. Your project, and your product, will be better for it.