Write documentation first, then build

VisiCalc started as a reference card.

The Nest thermostat started as a press release.

AWS, seemingly, started as a 128-word memo.

“Writing is a way of finding out,” wrote Kettering University’s Marvin Swift in Harvard Business Review, 49 years ago. Finding out what to think, and what to build.

Measure twice, cut once.

It all starts as an idea, a tiny speck of something that could be. You can picture it; it almost feels real. Now you just have to translate your vision into reality.

So pull out a pen. Start writing.

The temptation is to jump straight into building mode, to write code or build wireframes or sketch drafts of what you want to create. The better idea is to write your idea down as a way to think it through and improve upon it. Then, when you start building, you’ll know exactly what to build, and why, and you’ll have pre-written documentation at launch.

It’s not just you, either; the best things are never created in a vacuum (unless you’re running a lab on a space station). You’ll have a team, of employees or testers or customers, at least. You’ll never be able to convey everything you’re thinking about an idea; you’ll forget something every time you tell the story, add another little bit, an implicit promise your final product might not be able to keep.

Write your idea first. You then have a script to follow, a consistent way to share your story with others. We’re this, not that, here’s why.

VisiCalc's original documentation

The original PC spreadsheet, VisiCalc, was dreamed up by Dan Bricklin, developed by Bob Frankston in a Massachusetts attic. “I did more work figuring out exactly how the program was supposed to behave,” said Bricklin in his TED talk. Figuring out required writing.

So the first spreadsheet came to life first as documentation. “I wrote a reference card to act as documentation,” said Bricklin, complete with a hand-sketched and annotated facsimile of VisiCalc’s interface-to-be. Writing helped Bricklin consolidate his ideas, get everything the original spreadsheet would do down on 5 concise pages of documentation.

The documentation was the original pitch for the software. “It helped me ensure that the user interface I was defining could be explained concisely and clearly to regular people,” said Bricklin. It directed the program’s development, as the team decided how something should work ahead of time instead of just detailing how the program worked and hoping people would understand. “If we couldn't figure out how to explain a feature on the reference card we would change the program,” added Frankston.

When everything was clear and it was time to code, Bob Frankston kept the documentation going, writing real English alongside code. “Anything that might surprise someone reading the code was carefully documented,” said Frankston. It clarified his thinking about why the code was written the way it was and insured his mind against forgetting how something worked. “My assumption was that I would forget those key points myself,” said Frankston. “It also helped others who would read the code but the primary audience was me in the fog of coding.”

And when it was time to ship VisiCalc, the documentation was ready, waiting only to replace Bricklin's handsketched interface with a real screenshot. We were “busy working on the product,” too busy to write documentation, goes the common excuse for poor documentation. The VisiCalc team saw it the other way; there was too much at stake to not write the documentation first.

Nest's original box, via the Internet Archive, nearly unchanged a decade later

The Nest thermostat came to life first as something far simpler: A press release and packaging.

“When you write a press release you say, ‘Here. This. This is what’s newsworthy. This is what really matters,’” wrote Tony Fadell in Build. You’ve got this huge vision, he explained, more than you could possibly build. And in a press release, you’ve got 30 seconds of someone’s attention. Only the most important ideas get noticed.

So Fadell wrote the press release first. That simplified, streamlined vision then was the grade by which the Next thermostat was judged. If a new feature idea came up that didn’t fit, it was cut—for now, at least. The press release was what needed to be shipped, no more, no less.

Much like the classic elevator pitch, of a quick story about your startup you could tell an investor as you’re traveling from the first to the fourteenth floor, a pre-written press release gives your idea boundaries. Limits. It’s a story to share and a standard that tells you when you’re ready to ship.

Then packaging. With the pitch for the Nest in hand, the next thing the team built was the box. “The packaging led everything,” said Fadell. “The physical limitations of the box forced us to zero in exactly what we wanted people to understand first, second, third.” You go from a one-page press release to a few square inches, from sentences to summaries. Along the way, you refine your thinking, until you’ve distilled the essence of the product down to something you’d pick up off the shelf and buy.

---

Apple’s always taken documentation seriously; Fadell honed the old tradition into its simplest possible implementation. But the Macintosh, too, started life as documentation—as The Book of Macintosh, written by Apple’s original documentation specialist, Jeff Raskin, and team. “If you're working on a project and you'd like to manage it well, you have to have things documented,” said Raskin. “You’ve got to have a paper trail.”

Amazon founder Jeff Bezos agreed, famously insisting on every meeting starting with 4-page memos instead of PowerPoint presentations. “The reason writing a good 4 page memo is harder than ‘writing’ a 20 page powerpoint,” wrote Bezos in an internal email, “is because the narrative structure of a good memo forces better thought and better understanding of what's more important than what, and how things are related.”

So when Bezos—in a possibly apocryphally, 128-word memo—wrote that “All teams will henceforth expose their data and functionality through service interfaces,” it was a focused idea that led to Amazon building web services for which it’d be it’s own best customer, and turned AWS into the cloud computing juggernaut it is today.

The traditional carried on to the latest AWS services. When Amazon sets out to build a new service, says Amazon machine learning engineer Eugene Yan, "before writing any code, engineers spent 18 months writing documents on how best to serve customers." Once they start coding, they know exactly who will be using the product, why they're using it, and what they anticipate the service will provide.

Write. Rewrite. Revise. Then do.

“Writing is a way of finding out,” wrote Swift decades ago, but he didn’t stop there. “Rewriting,” Swift continued, “is the key to improved thinking.”

Swift conceptualized writing an internal memo about excessive copier use. You need a policy, so you start writing one, thinking it through in real-time. Then you revise, trying to find the right balance between something wordy and imprecise or something short and curt. Should all personal copies be banned? Should people get fired for extraneous copies? Or is this whole thing getting overblown?

In writing and rewriting your memo, your idea, you refine your thinking and writing together.

If you get that thinking out of the way before you start building, before you write the first line of code or lay the first brick, you’ll have a much better shot at creating something great. You’ll have great documentation ready to help your customers from day one, too.

from Hacker News https://ift.tt/9cW5xNO