I was looking through some classic (i.e., old) examples of technical writing and noticed how the format of application programming interface (API) reference topics hasn’t really changed since these examples were published in 1988 and 1992.
Is this because there’s been no innovation in technical writing during the intervening 30-ish years or, perhaps, we’ve found something that works, so why change? Taking that a step further, if what worked 30 years ago still works, is there any more room for innovation in tech writing?
Here are a couple of examples that I found in my library of software documentation. (It’s a library of printed documentation so there’s not much in there from the 21st century.)
MS-DOS Encyclopedia (1988)
The first example of classic documentation is from the Microsoft MS-DOS Encyclopedia (Ray Duncan, Microsoft Press, 1988), a 1,570-page collection of everything you’d need to know about programming for MS-DOS (v3.2) in 1988.
It starts with how MS-DOS was originally developed, continues with conceptual overviews of the different operating system functions, how to create common applications and extensions to the operating system, and various reference topics, such as the interrupt example I included here. It’s a one-stop reference manual that would prepare any MS-DOS programmer or device-driver developer for successful coding experiences.
This 33-year-old encyclopedia presents information in a format that you can still see used today.
- Overview
- Conceptual content
- How-to articles of common tasks
- Reference topics on various aspects of the product
- Cross references as make sense
The content in the example reference pages that I included also follows a format that is still seen today:
- The function name (SetTime)
- A description of what it does
- The parameters you pass to it
- What the function returns
- Notes
- Related functions (cross references)
- A code example (such as this one)
Windows API Bible (1992)
Fast forward a few years to 1992. Microsoft Windows (3.1) is all the rage and so it made sense to publish the Windows API Bible: The Definitive Programmer’s Reference (James L. Conger, Waite Group Press, 1992). This bible had only two-thirds of the page count (1,057 pages) as the encyclopedia and contains only reference topics for the functions in the Microsoft Windows API.
Again, the sample reference topic from this book has a familiar layout of its reference content, although it’s slightly different from the previous example.
- Function name
- Purpose
- Syntax (how you would call it from a program)
- Description
- Use
- Return value
- See also (cross references)
- Parameter descriptions
- Code example
My favorite part of this book is where they describe how they published the book.
Their colophon provides a nostalgic peek into how we wrote technical docs back then:
- Words on IBM PC
- Graphics on a Mac
- Page design in PageMaker (on a Mac)
- Screenshots in .BMP files, converted to .TIFF for publication.
Now that I look at it, that still looks familiar.
Good times!
Where to next?
So, if we’re still using the same information format for reference topics as we did 30-some years ago, is there room for innovation?
Of course!
Perhaps not in the layout of API reference topic information. This format seems to have withstood the test of time. There’s been some innovation in presentation (we don’t sell too many 1,000+ page books anymore, for example). Some API references docs now offer dynamic and interactive example code, which can be useful. HTML docs support cross referencing that doesn’t involve lots of bookmarks in your encyclopedia. And it’s obvious, that having all this information available without the need to store (and lug around) 1,000+ page books is certainly a back-saving innovation even if it uses a 30-year-old format to present the information.
In Measuring the value of technical writing, I showed a curve of diminishing returns. I’d argue that the format of the information presented in today’s reference topics is towards the right end of that curve. I don’t think there’s much to gain from tweaking something that seems to have held up well over the years. If you’re looking for a good place to start when creating your reference docs, the examples from 30 years ago seem as good of a place to start as any.
Where we need innovation in tech comm, in general, which trickles down to API reference topics as a specific example, is in assessing the performance of the content that we produce. Five years ago, I presented a paper that suggests we find ways to collect better data about how the content we write to learn how it’s serving our audiences. That is where we need innovation first. With better information, we’ll be able to identify where innovation in the content is needed and demonstrate how much it helps.
Who knows, this information might provide the insight into an innovation that will endure for the next 30 years of technical documentation.
One Reply to “Is there any more room for innovation in tech writing?”