What can the open source software of today learn from the history of software documentation?

Accepted Session
Short Form
Scheduled: Tuesday, June 21, 2016 from 1:30 – 2:15pm in B204


In the early years of easily distributable software, technical writers and the documentation that they produced were a crucial part of the software development process. Why? What kinds of contributions did they make, and what might their close cooperation with the programmers of their day teach us about how to manage open source projects better today?


I’ve been exploring the history of software documentation from the 1970s to the present for over a year now. One summary version of the conclusions I’ve come to thus far is pretty simple: everyone who deals with documentation could stand to learn quite a bit from the past.

But I’ve been thinking lately that software development more generally, and open source software especially, could really stand to pay attention to some of those same lessons from the past. Here’s what I mean, and what I’d like to tell stories about and put together the pieces of for a talk at OSBridge:

Once upon a time, technical writers were considered central and critical to the success of early software projects. Indeed, in some ways they provided the only entry into such projects, in the days before distributable compiled programs, when printed instruction sets represented early consumer users’ only means of providing commands to the computers they had so painstakingly acquired (I’m talking about the mid-to-late 70s here, for reference.)

Microsoft and Apple changed all that, but they did it with a lot of help from writers and designers who were deeply embedded in what we now call the product development team. In those early years, writers (the group I know about the most) worked very closely with programmers, interviewing them, printing up drafts of manuals and poring over them painstakingly together, to make sure that they provided consumers of the software with everything they needed to get the jobs done that they had bought the software to help with. All the stories I’ve heard and read suggest that in those early exciting days there was a much clearer acknowledgment (in practice, not just in theory) of the fact that it requires a multitude of roles to ship a successful software project than we often see today.

My talk would tell some of those early stories, and suggest ways that we might find our way back to a vision of shared roles coming together to make great and accessible software. A lot of people are working to make such a vision a possibility; I’d like my words to help move it forward.

Speaking experience

DC API Meetup, April 2016: "Documenting Your API: Options and challenges"
APIStrat 2015, Austin TX: "Your API Needs Technical Writers"
Write the Docs EU 2015, Prague, CZ: "Back to the Future: Tales from the history of software documentation" (yes the proposed talk builds on this talk)
Dev-to-Dev Summit, February 2015, SF: "Documenting REST APIs" (with Jason Wiener)
Write the Docs PDX Meetup, November 2014: Documenting REST APIs (with Jody Bleyle, Salesforce)


Leave a private comment to organizers about this proposal