Categories
Business Marketing Process Rants ROI Training Uncategorized Writing

How to Improve Documentation

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.

Categories
Business Process Uncategorized Writing

Can Cartography Teach Us About Documentation Design?

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.

Categories
Business Computer Languages Language Process Tools Uncategorized Writing

Technical Writing for the Cloud

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.

Categories
Business Flare Process ROI Tools Uncategorized Writing

Lowering the Cost of Documentation

 

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.

Categories
Computer Languages Language Marketing Process ROI Training Uncategorized Writing

Documentation Needs vs Wants: What’s the Value Proposition?

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.

Categories
Business Computer Languages Language Process Tools Training Uncategorized Useful Links Writing

Designing Effective API Documentation

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.

Categories
Business Training Uncategorized Writing

Why Bother Writing Technical Documentation?

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.

Categories
Blogroll Business Process ROI Tools Training Uncategorized Writing

Should You Outsource Technical Writing

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.

Categories
Process Training Uncategorized Writing

The Role of the Technical Writer

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.

Categories
Business Language Marketing Process Tools Training Uncategorized Writing

Documentation for the Brave New World

From touch screens of various sizes, to Microsoft Kinect™, Google Glass, Fitbit, and Square, we’re seeing a panoply of new devices that broaden both what technology can do and how we interact with it. This explosion of new interaction technologies has even created a bit of a hiring frenzy for interaction, user experience designers, and human computer interaction specialists whose job it is to design how exactly we are going to get all these new toys to do what they are supposed to. Dreaming up fantastic new ways to interact with all this fancy technology is one thing, but how do those dreams become applications, and how do people know how to use them once they get them?