Ignore previous directions 3
This newsletter is not written on a train for a change.
A short history of documentation driven development
With the renewed interest in specification first development with AI, I thought this early example of documentation driven development from 1975 was interesting. You know I like some history. Wang was an interesting company, founded in the 1950s by An Wang, who moved from China, went to Harvard and decided not to return home, despite the difficulties he faced. Wang became a pioneer in word processing, as the company shifted from selling to scientific and technical users, as a calculator pioneer to the larger general office market. Wang was obsessed by beating IBM, having sold a core memory patent to them to fund his company initially, and he did ship word processors before them, and built a huge company on the back of them.
I was reminded of Wang as there was a discussion on the Commoncog forum about how early adoption of new technologies always looks more continuous than late adoption, and the early adoption of word processing was secretaries and the typing pool adopting them. But the technology in turn removed those roles, and everyone became word processing operators, intially with a lot of grumbling from the people who didn't like doing that.
From Riding the Runaway Horse: the rise and decline of Wang Laboratories by Charles Kenney.
They began with an interesting approach. Moros suggested that rather than starting with the design of the machinery, that they write a manual for the ideal word processor, a manual that would place the technology, as Moros put it, “at the level of the user.” Step one would be to write the manual; step two, to see if they could bring to life the wish-list that the manual would embody. After six months of labor, they completed a ninety-six-page user’s manual, and gave it to the Doctor. He reviewed the document and said: “I like. You build.” Koplow immediately set about trying to create the machine their user’s manual described. It was one thing to write a manual for the ideal machine, and quite another to be able to create the hardware and the software for such a beast. The true beauty of the machine lay in its simplicity, for it was vastly easier to use than any computer ever built. From the moment the switch was turned on, the user was presented with straightforward choices at every turn. The choices were offered in plain English, not computerese. Koplow and Moros knew users lived in mortal fear that if they pressed the wrong button by mistake, an entire file would disappear into the stratosphere. So they made the machine immune to such errors. What Wang Laboratories had done was to take the power of computing out of the priesthood and place it into the hands of average high-school graduates who didn’t know the difference between a megabyte and a dog bite. “With ten minutes' training you could use the machine,” says Koplow. “It was just intuitive. There was nothing like it in the world.”
I can't find the document they wrote, although there is a much longer interim manual for the production system available which may well be an expanded version.
I actually can't find any earlier examples of documentation first development.
(I also went around a bit of history of editing diversion. This year is the 65th anniversary of the predecessor of vi, Colossal Typewriter, which was succeeded by Expensive Typewriter.)
This was also more or less what Dan Bricklin did when building VisiCalc in 1979, starting with prototypes and then going to documentation
So I decided to build a prototype. I went to a video terminal connected to Harvard's time-sharing system and got to work. One of the first problems that I ran into was: How do you represent values in formulas? Let me show you what I mean. I thought that you would point somewhere, type in some words, then type in some somewhere else, put in some numbers and some more numbers, point where you want the answer. And then point to the first, press minus, point to the second, and get the result. The problem was: What should I put in the formula? It had to be something the computer knew what to put in. And if you looked at the formula, you needed to know where on the screen it referred to. The first thing I thought was the programmer way of doing it. The first time you pointed to somewhere, the computer would ask you to type in a unique name. It became pretty clear pretty fast that that was going to be too tedious. The computer had to automatically make up the name and put it inside. So I thought, why not make it be the order in which you create them? I tried that. Value 1, value 2. Pretty quickly I saw that if you had more than a few values you'd never remember on the screen where things were. Then I said, why not instead of allowing you to put values anywhere, I'll restrict you to a grid? Then when you pointed to a cell, the computer could put the row and column in as a name. And, if I did it like a map and put ABC across the top and numbers along the side, if you saw B7 in a formula, you'd know exactly where it was on the screen. And if you had to type the formula in yourself, you'd know what to do. Restricting you to a grid helped solve my problem. It also opened up new capabilities, like the ability to have ranges of cells. But it wasn't too restrictive -- you could still put any value, any formula, in any cell. And that's the way we do it to this day, almost 40 years later. My friend Bob and I decided that we were going to build this product together. I did more work figuring out exactly how the program was supposed to behave. I wrote a reference card to act as documentation. It also helped me ensure that the user interface I was defining could be explained concisely and clearly to regular people. Bob worked in the attic of the apartment he rented in Arlington, Massachusetts. Bob bought time on the MIT Multics System to write computer code on a terminal. And then he would download test versions to a borrowed Apple II over a phone line using an acoustic coupler, and then we would test.
You can see the five pages of the reference cards here.
Another story of the success of documentation driven development was from Roberto Ierusalimschy, who told me that every time he wrote a new major version of Lua, he would rewrite the Lua book and if he could not explain the changes in an understandable way he would rewrite the feature until it made sense to explain.
The original Amazon Working Backwards definition from 2006 has a full documentation driven step
The Working Backwards product definition process is all about is fleshing out the concept and achieving clarity of thought about what we will ultimately go off and build. It typically has four steps: 1. Start by writing the Press Release. Nail it. The press release describes in a simple way what the product does and why it exists - what are the features and benefits. It needs to be very clear and to the point. Writing a press release up front clarifies how the world will see the product - not just how we think about it internally. 2. Write a Frequently Asked Questions document. Here's where we add meat to the skeleton provided by the press release. It includes questions that came up when we wrote the press release. You would include questions that other folks asked when you shared the press release and you include questions that define what the product is good for. You put yourself in the shoes of someone using the product and consider all the questions you would have. 3. Define the customer experience. Describe in precise detail the customer experience for the different things a customer might do with the product. For products with a user interface, we would build mock ups of each screen that the customer uses. For web services, we write use cases, including code snippets, which describe ways you can imagine people using the product. The goal here is to tell stories of how a customer is solving their problems using the product. 4. Write the User Manual. The user manual is what a customer will use to really find out about what the product is and how they will use it. The user manual typically has three sections, concepts, how-to, and reference, which between them tell the customer everything they need to know to use the product. For products with more than one kind of user, we write more than one user manual. Once we have gone through the process of creating the press release, faq, mockups, and user manuals, it is amazing how much clearer it is what you are planning to build. We'll have a suite of documents that we can use to explain the new product to other teams within Amazon. We know at that point that the whole team has a shared vision on what product we are going the build.
The Working Backwards book by Colin Bryar and Bill Carr says
Jeff tried many different ideas, some of them seemingly crazy, like starting a project proposal by writing a user manual or a technical API guide, relying solely on mock-ups, and other approaches to visualizing the outcome of the project. I remember getting frantic calls from nontechnical product managers saying, “Colin, I’m supposed to meet with Jeff next week. Can you send me a good example of a user manual? Also I’m supposed to write something called an API guide but have no idea what it is!” We were not committed to any of these experimental formats and stopped using them when we realized they were counterproductive.
They settled on the PRFAQ, led by the press release, as the most customer focused document.
To make a more lightweight process, Tom Preston-Warner defined Readme Driven Development in 2010.
Write your Readme first. First. As in, before you write any code or tests or behaviors or stories or ANYTHING. I know, I know, we’re programmers, dammit, not tech writers! But that’s where you’re wrong. Writing a Readme is absolutely essential to writing good software. Until you’ve written about your software, you have no idea what you’ll be coding. Between The Great Backlash Against Waterfall Design and The Supreme Acceptance of Agile Development, something was lost. Don’t get me wrong, waterfall design takes things way too far. Huge systems specified in minute detail end up being the WRONG systems specified in minute detail. We were right to strike it down. But what took its place is too far in the other direction. Now we have projects with short, badly written, or entirely missing documentation. Some projects don’t even have a Readme! This is not acceptable. There must be some middle ground between reams of technical specifications and no specifications at all. And in fact there is. That middle ground is the humble Readme. Consider the process of writing the Readme for your project as the true act of creation. This is where all your brilliant ideas should be expressed. This document should stand on its own as a testament to your creativity and expressiveness. The Readme should be the single most important document in your codebase; writing it first is the proper thing to do.
You can see in this history the growth of more agile approaches, and the tension between full understanding of a product versus iteration and prototyping.Working Backwards is clear that the PRFAQ should be a living document as more is learned in the later stages of building; VisiCalc was written in two months though and shipped the original design. Much of the difference depends of course on the complexity of the product and what you actually need to understand it.
Nature
The local pyramidal orchids just started flowering, I found some yesterday. Orchids cannot grow without symbiotic fungi as their seeds are not viable on their own, so they grow largely in places that have not been farmed; these were in the churchyard.
