Documentation-Driven Design (moving the caboose)

This month's Write The Docs ATX meetup featured Ian Buchanan, Senior Developer Advocate at Atlassian: Future-Proof Your Tech Writing Skills with Specification by Example. He was inspired by reading Specification by Example: How Successful Teams Deliver the Right Software (Gojko Adzic, 2011), which is deservedly famous. It describes the holy union of software requirements, project documentation, and test automation: (1) collaborate widely on requirements, (2) specify them through tests, and (3) automate their validation, so that the tests serve as a living documentation of the requirements. Ian's thought was that test-driven design should not be limited to internal use: it could and should be surfaced to example-driven design, meaning code embedded within user documentation, code that runs and validates.

Sadly, tech writing does need to be future-proofed. Writer teams are shrinking while release cadences are accelerating. Expectations for doc quality continues to drop along with its resourcing, driving the worsening problems that Ian identified:

• Dead but not gone - Interfaces that are documented are no longer available
• New but not seen - New interfaces exist in code but are not documented
• Broken but not detected - Interface changes cause doc examples to break invisibly

Ian's brainstorm is to elevate and code up doc examples to serve as living external specifications that are automatically validated: they show errors when they're broken. This makes docs more valuable, visible, and trusted (as are, by extension, the writers!). The TDD cycle (write the unit test, test fails, code to test, test passes) would be expanded by one layer: example fails, unit test fails, and so on.

I latched onto the idea of moving up documentation work immediately after specification, before any tests and coding. What if we weren't talking about just the code examples in the docs but rather the entirety of the user docs themselves?

The seed of my discontent was planted by the owner of an enterprise product that I documented 20 years ago. He was keen on single-sourcing of any kind (shared code, cross-platform docs, docs and training), and he saw opportunity to streamline RFPs as well. Prospects in this vertical market were used to buying custom software, so they commonly required delivery of official specifications, to hold as contractually binding as to promised functionality. He decided that the product documentation could serve that purpose well enough, and so the documentation became the living specification, by decree. In short: if the docs said foo was possible, then the dev group was on the hook to make it so.

Yet the development process didn't change to match that implied path (describe the interfaces in example-rich user docs before coding them): documentation and training remained the caboose at the end of the waterfall line. However, Agile software development is slowly bringing product documentation into the fold, so perhaps the time has come?

Picture this:

Stakeholders work with the development team to settle on a list of specifications. Tech writers work with PM/BA and other UX/CX team members to develop documentation drafts that cover all of the proposed functionality. They capture the key use cases and motivation (user goals) and create interface mockups, diagrams, and meaty scenario-driven examples. In my experience, nothing sparks clarifying conflict like a diagram: making it visual forces people to recognize their own mental model and reveal their assumptions to the group.

My pitch: Let us host the constructive battles over usage, naming, task flow, and consistency before a single line of code is written, and let user docs be that highly visual battleground, the living specification, slowly morphing into the final deliverable (mockups become screenshots, pseudocode examples become real code). With such documentation to work from, writing test plans becomes much easier. This also prevents engineering waste: developers can reconsider implementation paths based on the emerging doc details, which improves the odds that they find an optimal one. It's excruciating to redo code and tests because of missing the goal; it's even more painful to just ship it and live with the awkward implementation!

To future-proof tech writing, let's move the caboose of documentation up behind the engine of specification. Get us up front so that we can actively drive CX, rather than having us passively document around (and merely grieve) the interface that was coded as a result of unaired assumptions. Truly Agile teams would stop seeing documentation as a necessary expense but as central to getting the product forged in the first place, and that would change everything.