The odd cadence of narrative engineering design documents
Within Microsoft, it was popular for a while (maybe it’s still popular) to write narratives surrounding every proposed feature. Here’s an example:
Alex works as a developer for a company that makes widgets.
The company plans to manufacture widgets that take advantage of feature Foo.
Alex has read that the Windows Blorg service supports Foo and decides to explore the possibility of integrating the company’s widgets with the native Foo support in Windows.
Alex has downloaded the Blorg SDK and plans to implement a prototype.
Alex likes Windows because of the many widget-related services already available in the platform.
Alex writes a function that takes a BlorgServiceRequest ticket and zondrizes the ticket in order to activate the Foo feature.
This document introduces a new API for zondrizing BlorgServiceRequest tickets.
It starts with Alex being this total n00b who downloads an SDK to learn more about this Blorg thing. And then suddenly Alex is this Blorg expert running around zondrizing tickets like a boss.
At least the introduction didn’t finish with
Alex is delighted that Windows makes it so easy to zondrize Blorg tickets for Foo.
Light
Dark
4 comments
Of course not. It would end with “This new API empowers Alex to achieve more efficient ticket zondrization.”
If the spec doesn’t say that Alex is thrilled with Windows, then it won’t tie into an overall theme, and features that don’t fit into a theme are likely to be cut 🙂
At Amazon, “surprise and delight” was one of our core product principles — pretty sure I’ve seen “Alex is surprised and delighted that [AWS] makes it so easy to zondrize Blorg tickets for Foo.”
For a while, everything was “terrific”, a word that I thought had died out in the 1950s, but right now where I work, everyone is always “beyond thrilled” about everything. Many of my colleagues are so far “beyond thrilled” they’ve come around full circle to abject misery.