According to Wikipedia, a subject matter expert (SME) is a person “who is an authority in a particular area or topic.” When a company engages a technical writer, in addition to working with the actual product he or she is documenting, the writer must rely on the SME as the source of all knowledge, the one person who can explain how the system works and, perhaps more importantly, why it works that way.
Recently, a prospect called us about a training guide he needed written for a new enterprise application his company had recently purchased and was trying to implement. Unfortunately, he had already paid the company that developed the application to create training materials but found, once he had a chance to review the materials, that they were not only impenetrable and useless from a user’s point of view but mostly incorrect as well. A complete waste of money. Alas.
Objectivity tends to be one of the core values of technical fields. The fundamental laws of physics dictate the properties of microprocessors, and chemistry defines the properties of the materials we use. These methods make up the API, determining how that application behaves and what it is capable of doing. The way that people interact with technology, however, is anything but objective. They bring a lifetime’s worth of experiences that guide their behavior and frame their expectations for both what the technology will do for them and how it will perform its duty.
Technical Writing for the Cloud
By: Eric Sedor
Eric Sedor, a frequent contributor to the Shoap Technical Reader, is a senior software engineer at MongoLab, a cloud-based database provider located in San Francisco. Eric cut his technical writing teeth at Shoap Technical Services before returning to his true passion, software engineering.
The Cloud encapsulates the idea of a distributed system built of formable, destructible, re-creatable components. Even the data within cloud systems is redundant and spread out, capable of being restored in parts to specific points in time, if necessary. Cloud systems even overlap one another.
Wikipedia defines single sourcing as “a content management method which allows the same source content to be used across different forms of media and more than one time. The labor-intensive and expensive work of editing need only be carried out once, on only one document. This reduces the potential for error, as corrections are only made one time in the source document.” A decent, I think, explanation of what this mysterious approach to documentation is all about.
Do a little research and the prevailing opinion expressed by those who write and those who want documentation is that it’s not done because (as I’ve written in a prior blog — see http://www.shoap.com/why-bother-writing-technical-documentation/):
• It costs money.
• No one wants to do it.
• No one uses it.
While those facts remain true, the more important issue – what kind of documentation do companies actually need? – rarely gets addressed. Perhaps it’s time to talk about that issue.
The user interface of an application – even one with a convoluted design – gives users some sense about how to navigate the application. It may be painful, but users can usually muddle through if they have to. APIs, on the other hand, offer no natural affordances or signifiers allowing developers to learn how to use the API. Therefore, good documentation is crucial for any API project.
For many companies, it’s easy to see why technical documentation gets ignored:
• It costs money.
• No one wants to do it.
• No one uses it.
It’s no surprise that technical documentation is the last item to make it on the project plan and the first item to cut from the budget. End of story.
Many companies labor under the incorrect assumption that keeping certain functions (like technical writing) in-house gives them the greatest return on investment. Not true. Here’s why.
Eric Sedor is a senior software engineer at MongoLab, a cloud-based database provider located in San Francisco, and frequent contributor to The Technical Reader. Eric cut his technical writing teeth at Shoap Technical Services before returning to his true passion, software engineering.