The Agile Development author Gojko Adžić caught us red-handed lying in our spec for user-interface specific user stories, when we wrote “As a user, I want to register in order to log in”…
The lie starts with the whole premise. “As a user, I want to register”… No I don’t. As a user I don’t want to give my private information to another site, have to argue with some arbitrary fascist filter about which combination of letters and numbers is strong enough, try to guess what’s written on some random distorted image, and then have to remember another set of fake privacy answers. That sentence might be in a user story format, but it’s far far from a user story. It’s grammatically correct, but completely false…
So which narrative would be closer to the truth?
it’s not the users who want to register or log in, but possibly the web site operators who want to identify users so that they could charge them correctly, or compliance officers who are concerned about privacy complaints, or marketers who want to harvest e-mail addresses.
Stories in Agile Development are not just a fake brainless template we fill in — we still have to think and capture the true needs of the stakeholder.
As a tech writer I often catch myself writing stories such as “as an administrator I want to read documentation how to configure XYZ”. No. “I, as an administrator” actually do not want that. I maybe want release notes that inform me which new features were integrated. But otherwise, what I want is a user-interface, wizards, and templates, that are intuitive enough so that I do not have to dig out documentation. As a tech writer on an Agile team, I represent this point of view of the stakeholders.
It’s a typical case of in-depth expertise versus broad big-picture knowledge: You as tech writer look at the whole UI, while a developer does not necessary know more than his component. Developers sometimes use synomyms for feature names — because they are not aware of the larger context in which their UI text appears, or (more commonly) because the dev team simply has their own lingo, while the UI uses official “marketing-approved” terminology. It’s my job to point that out and make sure the terminology is consistent throughout.
While documenting, I try out the workflow, e.g. on a virtual machine. When I get stuck, I send the developer screenshots with questions. A tech writer is often the first to try a new feature (even before QA). I see this new error message, this new menu item, this button or label etc, in the same context as the customer. If I can’t get this to work with the developer sitting next to me, then the customer won’t stand a chance.
If a workflow is hard to document, then it’s hard to perform. If it’s hard to perform for customers, they will simply call support. Remember, you as tech writer should dare make suggestions how to improve a workflow. This is also in the interest of the developers, who will have fewer calls to answer.