Capturing the narrative
A question came up on the BDD list recently, and based on feedback I thought it would be useful to post my answer to a wider audience.
What artifacts do folks normally use to capture the “scenario-extraneous” details that come out of discussions/meetings/etc? If I’m developing a “living document” shared by me and my stakeholders, I’m assuming capturing those details would be useful, and that I would want to have them “at hand” for anyone who shows up late to the game.
The default answer for lots of teams has been “put it on the wiki” but I’ve seen many environments where the wiki is where information goes to die, nothing more than a hipster version of SharePoint. Other than the executable specification itself, I see several kinds of information that are useful to track:
Narrative ¶
These are the conversations we had around various decisions we made. In particular it is useful to capture:
- what we considered when we made a decision (about architecture, about a particular aspect of the domain model, about monitoring, …).
- what we dismissed. I can see in the code that we ended up doing X. I don’t know we also considered Y and Z but went with X because unicorns.
- who was involved, both within and outside of the team.
My preferred medium for this is a product blog. You have timestamped entries so you can see when various conversations happened and decisions were made (or deferred). People can comment, either at the time or much later. You can revisit decisions to see what we considered. One of the big benefits is that it reduces a lot of low grade repetition:
“Why are we using Maven? We should be using hipstr* instead!” “Take a look at the blog entries tagged “build” and you can see the various discussions we had. If you think something has substantively changed, or you have something to add, let’s have the conversation again. In any case you’ll understand how we got to where we are.” *crickets*
You can spin up a new WordPress instance on a VM in a few minutes.
* There is no such thing as hipstr. If there were it would probably be a build tool.
Standards ¶
Over time, we start to settle on How We Do Things Round Here. Things like documentation style, code style and conventions, packaging and naming, error-handling, in fact anywhere that a) everyone has an opinion and b) it really doesn’t matter as long as we’re consistent. These I want on a wiki. The wiki has to have excellent search (good ranking, uses word variants) and someone needs to be tasked with curating it, like a librarian. Part of on-boarding a new person is showing them round this wiki.
Backlog ¶
This is work we have committed to. I don’t care how the team stores this as long as it is visible to all the stakeholders. That means if people are non-local there needs to be either an electronic version or a daily photo of the board, emailed out or posted on the blog. (I really like this by the way. I haven’t used it myself but someone told me how they use these as a stop-motion replay of the sprint for their retrospectives. Shows some interesting trends.) It also needs to be lightweight enough that people aren’t intimidated by changing large swathes of it. I like Trello. Everyone seems to be using Jira, which astonishes me because it’s a (rather good) bug-tracker. Bonkers. For extra credit I also want to be able to get metrics out of it so I can measure e.g. lead and cycle times and WiP.
Ideas ¶
People come up with ideas for the product all the time. Users, operators, administrators, developers, testers, anyone. You want a mechanism for capturing that that’s different from the backlog, otherwise people dump all their half-baked ideas into the backlog, which makes lead time metrics meaningless and creates an implied contract that you’ll eventually deliver their thing (which you will inevitably disappoint them with). I call this a wishlist. I wrote one recently with a client, that we called “Dear Santa”. Simple idea capture, with submitter’s name, description, benefit and timestamp. You should review the stuff in the ideas dump on a regular basis, and look for clusters or just simple good ideas to implement.
There are no doubt other categories of information, but if you can nail these you’ve made a good start.
