User docs driven development

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'.