User docs driven development
I usually write the user documentation while features are getting implemented. This process reflects back into development and helps shaping them.
This is a post on our working culture at fortrabbit and how we craft our new platform - in the making.
Getting into the head of the user
A feature often starts with internal ideas discussed. Exchange with our clients is a common source too - see support driven development. After defining a feature in internal documentation with specs, we usually drift to technical implementation details.
But I also write the end user documentation as soon as possible, often before implementation is finished. We have a public documentation that can be found at help.fortrabbit.com for reference - the new one is in the making.
If you can't explain it simply, you don't understand it well enough.
This approach forces me to think about a feature from the users point of view. It helps to uncover usability flaws, potential misunderstandings and edge cases that we haven't thought about before. Sometimes we even drop or redo a feature when the user documentation reveals too big issues.
Practicing ubiquitous language
We all know that naming things is hard. I believe that it not only needs consistent language between interface and user, but even end to end. We should always use the same word to describe the same functionality. The user documentation should use the same terms, as how they are called in the database and internal functions.
Addendum
When researching for this article I found that 'Documentation Driven Development' (DDD) can easily be confused with 'Domain Driven Development' (DDD), both are usually closely related to 'Test-Driven Development' (TDD). This article has a focus on code comments as a starting point for API docs, see HN too. Literate programming is a related concept. And of course there is 'README-Driven Development', write your README first.
This Gist is close to my subject here.
Allow me invent the UDDD acronym: 'User-Docs-Driven Development', not to be confused with 'Ultimate Destruction Demolition Derby'.
Postscript
Back in 1996, Steve McConnell's "Rapid Development" listed a few ways to develop a spec. One of them was (p324):
User manual as spec — Instead of writing a traditional specification, write a user manual, and require the software to conform to the manual. Since you have to write the user manual at some point anyway, you might as well write it first and eliminate the redundancy you would otherwise incur by writing both a user manual and a specification. A variation on this idea is to write an on-line help system for use as the spec.
The approach given here seems a combination of user-manual-as-spec and evolutionary prototyping.