One Way to Document Extremely Complex Software
A Project
I recently worked on a project documenting a software piece from hell. Before I start talking about how I wrote the documentation, let me give you a little bit of background on the software itself.
Software: Reiterated, Complex, Multitiered…
As I understood it, the software was originally developed and written about 30 years ago, and over the decades it has been embellished in a piecemeal kind of way. Originally starting as a “green screen” or command line piece, it eventually was bolstered up with some graphical user interfaces. But often at its core, it still remained a command line piece of software. After several decades of this random embellishment by who knows how many different software developers, the entire software suite became an extremely complex nightmare that even its current product managers could not wrap their hands around. The original developers were either retired or passed on, and thus were not readily available for consultation.
The existing documentation set that came with the software amounted to about 27,000 pages (literally!), all developed over the last several decades! So how could we reasonably expect a customer to buy the product, and then scour literally thousands of pages of documents to figure out how to use it? Luckily, the hardware with which we were selling the software was limited in its use, thus allowing us to narrow down the content scope.
So my task was to document the software after being integrated with a certain piece of hardware, all of which was to be used for a limited range of industrial applications.
Confounded Again!
The problem that the product manager and I were faced with here was that our prospective industrial end-user audience could use the software and hardware integration for literally thousands of different industrial applications! Because there were already literally tens of thousands of pages of existing end-user content, we realized that anybody we sold this software/hardware integration to would be utterly dumbfounded as to where to begin development and integration to their industrial scenario.
The way we decided to address this problem was twofold.
The first did not involve much documentation. This first solution was to offer the end-user some hands-on training and engineering consulting to get them started with our product. Basically, our engineers would come in to the customer’s location, set up the device and software, help them write some code to get their industrial setup integrated with our software/hardware control platform, and then bill them for this service. The documentation associated with this for solution was limited, as the consulting service was mostly a quick and dirty hands-on operation.
Document for a Limited End-User Profile
The second way we addressed the end-user’s needs was for customers who did not opt for consulting. My software team and I instead developed an “all-inclusive end user profile.” This user profile basically assumed that the broad audience of customers that could possibly use our software/hardware platform would perform essentially the same set of procedures to set up their system. We called these standardized sets of procedures “workflows.”
As I mentioned before, these workflows only covered basic system setup. Because there are literally thousands of industrial customers out there – all of whom have developed their own in-house methods and associated code for addressing their own needs – there was no way that my team could possibly document the methods needed to integrate these thousands of scenarios. It literally would’ve taken thousands of years to do this!
This said, the end-user documentation amounted to about 220 pages of high-level information that could help the customer get going with a very basic setup.
The documentation project was exacerbated by the fact that the software was so old, that there was literally sometimes three or more ways to perform the same task! One literally could perform the task from the command prompt only, or by manually manipulating the operating shell (in this case it was Linux), or by using a Windows-like interface, or a combination of all of these.
The Result Was…
In the end, to simplify things we decided that the more modern end-user audience that would be using this software would be mostly accustomed to using an object-oriented interface or GUI to perform tasks. Therefore the procedures that I documented shied away from the command line and used the GUI whenever possible.
For more details on how the user guide came out, have a look for yourself:
Good post! I like it!
Yep, it's tech writing!