Many people imagine that in Agile we don’t use specifications – but the truth is, Agile needs them as much as any other development process. It’s just that Agile specifications take a different form, and are written in a very different way.
Agile is a mindset, not a fixed methodology
Agile, in fact, is not a methodology at all. It’s not how you produce software. It’s a mindset about how you produce software.
It started as a mindset for governance of flexible software development because things were getting slowed down by strict adherence to rigid top-down project management rules. Agile is about empowering simultaneous teamwork and networking.
It’s also based on the idea of continuous iteration – but continuous iteration in an environment of openness and responsiveness, which means listening, making mistakes, accepting that problems do occur and dealing with that.
The whole notion behind the Agile mindset is to engage the participation of every member of the team at every phase. And that implies co-responsibility. This is good news for technical documentation.
Two kinds of Agile specifications
From an Agile point of view, there are some difficulties with traditional specs.
So if we’re talking about a mindset in which change is constant, and we’re constantly repeating and reiterating development, what kind of software specifications do we provide? In Agile they take two forms:
- User stories
- Personas and empathy maps
User stories should not be confused with use cases, which define a technical process a user goes through. They are a way to describe what the user goes through in order to complete a task. It adds a human element. And personas tell us something about what the user – that human – is like.
Don’t specifications take too long to write for Agile?
In an Agile context, traditional specifications often take too long to be written. And also, because we’re in this Agile iterative process, the scope of specifications can change – and they should change as we learn more about the problems we’re trying to solve.
Maybe for each iteration, all we need is some sort of high-level spec. The details will get done as we iterate and reiterate, and then we can flesh out our specifications as we go.
Technical communicators in Agile development teams
How does a technical communicator fit into this? Aren’t we stuck, even in Agile teams, at the end after the dev decisions have been made? If you’re really doing Agile, the answer has to be “no.” But sometimes, it’s also our fault if it works that way.
I’ve seen situations where the engineering team invited the technical communicator to come in and participate in the design phase, which is the way that Agile is supposed to work. And the technical communicator responded, “No, I don’t want to do that. Just let me know when it’s done and I’ll document it.”
My response to that person was, “Are you crazy? We’ve been trying to get into the design phase for how many decades? Somebody actually invites you in and you go away?!”
The question of comprehensive documentation has been the subject of a lot of debate and discussion in the Agile community.
I’d suggest you read the original Agile Manifesto to get a better answer to that question. And keep in mind, when they speak of documentation, they are developers, and they’re talking about documentation of their code, not the docs you write.
The cardinal values for Agile software development include that individuals and interactions are more important than processes and tools. Agile values collaboration over contract negotiation, and responding to change by being flexible is more important than following a rigid plan. For technical content developers, this should be meat and potatoes.
Are you having trouble with specifications?
At Firehead we’ve developed a “Specifications on a shoestring course” with expert Ray Gallon. This is aimed at mid-level technical communicators and other content developers who use specifications as source material, or need to write specifications for products or internal processes.
On the course we’ll specify technical documents, and look at specifications for our internal procedures and practices.
If this sounds interesting for you and your development, you can buy the Specifications on a Shoestring course here.
Download our guide to specifications
Content expert Ray Gallon has written this checklist to help digital communicators like you, make the most of specifications and help integrate yourself into the product team.
