Documentation following the rules: the Case of the Laboratory Applications

A specialist scientific company had over the years produced many applications to assist with laboratory work. Some were simple calculation routines, and others controlled various pieces of laboratory equipment. None of them had accompanying documentation. Management was getting concerned about the long-term maintainability. Also, there had been critical comments from their accreditation body: for them the software was a black box, whose correct operation had to be taken on faith.

Read more ...

From developer to technical writer: the Case of the Java Tools Developers

A large systems manufacturer, assigning considerable manpower to open source software development, needed their code components to be documented. The users of these components were themselves software developers rather than end users, and no budget could be made available for the services of a technical writer.

Read more ...

Making documents available and findable: the Case of the Overworked System Administrators

In a large hospital, more than one hundred separate computer systems were active at any given time, ranging from medical imaging systems to the system that keeps track of who is wearing which lab coat. A handful of system administrators kept all those systems up and running. Even when they were off-duty they had to leave their cell phones switched on, because nobody else knew what to do when something went even a little bit wrong.

Read more ...

User guides: the Case of the Usable User Instructions

This "case" has many faces. All too frequently we come across software without usable user documentation. No documentation exists, or it isn't aimed at the end users, or it is incomplete. The result is always that people have to find out for themselves how the system works. In doing so, they waste vast amounts of time and effort without ever becoming truly productive.

Read more ...

Documentation under time pressure: the Case of the Threatening Penalty Clause

An industrial company had built both the hardware and the software for an external customer who needed to run a gas field in the desert. Producing the documentation specified in the contract proved more difficult than foreseen. All of a sudden the delivery date was looming. The contract contained a hefty penalty clause.

Read more ...

Writing work instructions together: the Case of the Unhappy Accountants

A manufacturer of artificial fibres had concluded a successful SAP implementation. Such a change in working practice affects the whole company. Unfortunately, the financial departments of the three working companies found it difficult to come to terms with the changes. Simple as the screens were, they were filled in incorrectly. This had potentially serious repercussions further down the line. Perhaps more importantly, general dissatisfaction with the new situation was slowly spreading.

Read more ...

System documentation to support outsourcing: the Case of the Missing Specs

A fast-growing supplier of e-publishing services found themselves increasingly outsourcing programming work to subcontractors, often located abroad. The sooner such subcontractors understand what has already been produced and what is expected of them, the better. Valuable time was being lost defining these issues. This not only cost money, it also meant that our client could not respond to requests from their own customers as rapidly as they would have liked.

Read more ...