So do you have any good ideas about keeping alive a documentation that is readable for anyone, even…
Bruno Feroleto
1

Who is the documentation for? If it’s for developers, your functional tests and unit tests are the canonical source of feature truth. Like BDD specs, they are the living documentation, but only developers need that kind of documentation.

BDD style docs fall short here because the technical limitations put a high maintenance burden on BDD maintainers, and add unnecessary abstraction to the mix which can obfuscate rather than clarify the subject being documented.

Make sure your test suites are readable and descriptive. Try to include a short description of the feature that captures why the feature exists.

Non-technical users typically need something much more explicit and concrete than user story specs, and they don’t care about test suites at all.

They need searchable video demos and tutorials demonstrating workflows step-by-step, including what buttons to press and where to find them. There’s no way to keep this kind of documentation “live”, but it’s the only kind real users care about.

We usually need good technical writers and video editors to create this kind of documentation. Developers generally lack the skills to do that kind of documentation well.

It’s possible to build first-time user tutorials right into the app. Some apps do this well, highlighting controls and explaining what they do. Some video games are really good at this.

Before you can do documentation well, you first need a good understanding of the needs of the people the documentation is intended for.

The reason I’m not a big proponent of live BDD DSLs is that user stories are quickly outgrown and inadequate to document the concrete features built by developers, and as such, become only a partial documentation solution for developers, and never provide adequate documentation for users.

So after the initial build, who are those kinds of docs serving, and are they the best docs for that particular audience, or can we do better?

Every time I’ve asked “can we do better than BDD user stories?” for a given audience, the answer has always been an easy “yes, of course”.