Lessons Learned in a Year of Docs-Driven Development - Jessica Parsons

Docs-driven development—writing documentation first, then building to match it—has become a practical operating system for teams trying to move faster without losing alignment. The central lesson from a year of using it at Nullify is that documentation can tighten feedback loops and reduce rework, but only if the organization treats docs as a managed workflow: scaffolded, reviewed, versioned, and actively read.

The approach starts with a simple rule: draft the docs that describe what a feature should do, then implement the feature to conform to those written artifacts. The practice can take multiple forms—code comments, spec files like Swagger/OpenAPI, and user-facing documentation—but the key is that docs are not an afterthought. Parity with agile is a recurring theme: describing a change is usually smaller and faster than coding it, so teams can iterate on the smallest unit of understanding before committing engineering effort.

Nullify’s rollout benefited from internal momentum. Leadership support was explicit: the CEO had long been a fan of readme-driven development, and the head of product had practiced docs-driven development during earlier work with the BBC API team. Communication norms also helped because the company is remote and relies heavily on written updates. Still, early enthusiasm didn’t prevent friction. The first major lesson was blunt: good intentions aren’t enough. People struggled with where to start, how to write effectively, and how to reconcile documentation time with coding metrics. Some felt guilty for spending time documenting instead of shipping.

To address that, the team built structure. Project templates in their knowledge management system (moving to Notion) define required artifacts such as user stories, internal workflow descriptions, and customer-facing docs. Naming conventions were standardized early so developers, writers, and marketing could share a common vocabulary. Templates also provided scaffolding—sections, guidance, and examples—so contributors weren’t staring at blank pages. Kristin’s customer-facing doc template, for example, included common headings plus tips and links to reference material.

The team also broadened what “documentation” means. Diagrams, wireframes, and even videos were used when they communicated better than text. But docs still needed a “driver”: someone responsible for enforcing the process, prompting teams to write before coding, and ensuring docs work counts in performance evaluation. The talk ties this to “glue work,” the often invisible coordination labor that keeps projects moving and that can disproportionately fall on women.

Once docs were being written, the next bottleneck emerged: getting people to read them and know what changed. The solution combined accountability and notification. Specific reviewers and deadlines were built into the workflow, with representatives from relevant functions (marketing, docs, development) reviewing naming and other key artifacts. Changes were tracked via GitHub when possible (for PR-based updates) and supplemented with human-driven issue tracking and Slack project channels when richer content lived in Notion.

When teams actually read the docs, the benefits were concrete: developers joining midstream could self-serve instead of scheduling catch-up pairing; parallel work became easier, such as front-end development against an OpenAPI spec while back-end endpoints were still being built; and support and marketing could ramp up earlier. Yet a final caution landed hard: docs-driven development doesn’t automatically guarantee user-centered outcomes. A feature that looked correct on paper failed a real-world test when an internal open-source user immediately asked how to turn it off—revealing the team hadn’t fully solved the underlying customer problem. The fix was to involve users sooner via user studies, lightweight feedback loops, and proxies like support, community forums, and sales when direct customer access is limited.

After a year, the conclusion wasn’t abandonment—it was escalation. The team planned to double down on docs-driven development, tightening the workflow so documentation becomes a reliable engine for alignment, iteration, and inclusive self-serve knowledge rather than a checkbox that gets written and ignored.