Documentation
Deliver Context and Clarity
For the high-tech industry, documentation projects can run the spectrum from highly technical product-oriented guides to technical marketing materials. But regardless of format, all material should be clear and succinct; technical doesn’t have to mean convoluted.
Good documentation is written for the appropriate target audience — executives, administrators, end-users, and other roles should know at a glance what to read. Technical guides should go beyond documenting the what, providing context by adding the how and why.
Write what your audience needs
For the high-tech industry, product documentation can typically be lumped into the following categories:
- Deployment/implementation guides
- Administration/operations guides
- User guides
- Developer guides
- Reference guides
- Getting started guides
- Write each document for the appropriate target audience, using language that speaks to them. Executives, administrators, technical decision makers, business decision makers, and end-users should all know what to read at a glance.
- Go beyond documenting the what–add value by discussing the how and why when appropriate.
- Provide a polished layout design for title page, chapter pages, facing body pages, etc. A professional documentation design enhances the product.
- Use screen shots and other graphics to reinforce the text. Although images can be a significant resource cost, they can also greatly improve the reader’s experience.
- Add tips, notes, warnings, and other “extras” in a document’s margins that highlight key functionality or warn of potential problems.
- Supply cross-references throughout the books and create detailed indices to help the reader quickly find related information.
Sample Documentation Projects
Operations Manual
A manual for defining procedures to transform data from one format to another for an enterprise data transformation device
Consumer-Oriented User Guide
A user-friendly product guide developed for the consumer market
Developer's Guide
A technical paper that goes beyond a basic API reference
Let's Talk.
Ready to discuss your business needs? I’m here to help.