2 Reasons Why Technical Writing Is Agile
“Agile” is not stopping writing, “agile” is starting thinking
Let’s start with history, as reported by agilemanifesto.org:
On February 11–13, 2001, at The Lodge at Snowbird ski resort in the Wasatch mountains of Utah, seventeen people met to talk, ski, relax, and try to find common ground — and of course, to eat. What emerged was the Agile Software Development Manifesto. Representatives from Extreme Programming, SCRUM, DSDM, Adaptive Software Development, Crystal, Feature-Driven Development, Pragmatic Programming, and others sympathetic to the need for an alternative to documentation driven, heavyweight software development processes convened.
As a technical writer, I’m interested in the quote’s last sentence: “[…] the need for an alternative to documentation driven, heavyweight software development processes convened.” Too many people stopped reading here, welcoming a documentation-free era.
The need to be light in the fast-paced software world is a common sense reaction to a demanding business environment. The seventeen people who met in 2001 focused on finding a solution to that need; they didn’t mean to appoint the documentation as the enemy to defy.
In fact, reading forward in the agilemanifesto.org:
The Agile movement is not anti-methodology, in fact, many of us want to restore credibility to the word methodology. We want to restore a balance. We embrace modeling, but not in order to file some diagram in a dusty corporate repository. We embrace documentation, but not hundreds of pages of never-maintained and rarely-used tomes. We plan, but recognize the limits of planning in a turbulent environment.
I dedicate this article to all people who stopped modeling, planning, and writing documentation just because the agile faith was revealed to the world.
As a discipline and mindset, technical writing helps us understand why that abandonment was and is a mistake.
There are two reasons why “agile” as a brand and faith is an alibi to abandon the discipline of managing products and projects; they are the same reasons why technical writing is the backbone of “agility”:
- Technical writing is communication, and communication is tough to tame.
- Technical writing is designing, and designing is a time investment.
Let’s get started.
#1: Technical writing is communication
Two out of four values in the Agile Manifesto involve communication:
Individuals and interactions over processes and tools
Customer collaboration over contract negotiation
Both values focus on the audiences of the communication and put what to do in the background. It doesn’t mean that what to do — processes and tools and contract negotiation — is irrelevant, but it’s a means, not the aim.
What’s more audience-centric than technical writing?
The path toward reaching a goal has specific problems that tend to distract attention from the goal itself. Building software is the path to satisfying customer’s needs, the goal. Technical writing is the path to communicate how that software meets those needs.
“Agility” needs effective communication, and technical writing is effective communication.
#2: Technical writing is designing
The other two values in the Agile Manifesto involve design:
Working software over comprehensive documentation
Responding to change over following a plan
Both values focus on designing the outcome: the software and planning sides.
It happens that some managers give more weight to the speed of execution — the time to market — than to the execution itself and also infect technicians with this mentality. The result is, again, that the means become the purpose, and the purpose — the outcome that serves the customer — is lost.
What’s more purpose-centric than technical writing?
Think of writing a document: immediately after defining the document’s audience, technical writers focus on the purpose of audiences when reading the document itself. Then, they plan how to reach that result.
That’s designing. It requires skills and time: it’s an investment. The world constantly changes, then investing is a risk of failure. The short circuit is to stop investing to avoid failures.
Yet, writing without purpose, like neglecting designing and planning software, is the step that leads to failure.
Conclusions
Technical writing is “agile” because it takes care of communication which is the backbone of the effort to satisfy customers. Technical writing is “agile” because it’s designing.
Following Vaughn Vernon in Domain-Driven Design Distilled (non-affiliated link):
Quote: It’s important to understand that the imagined economy of No Design is a fallacy that has cleverly fooled those who apply the pressure to produce software without thoughtful design.
Misinterpreting agility as liberation from design and the burden of documenting it is a mistake. Technical writing is the solution to that mistake.
If you enjoyed my article and found it helpful, please consider joining Medium through my referral link: you’ll support my writing and get into a sea of knowledge. No extra costs!
