“Waterfall is dead, long live Agile,” many voices cry, heralding a transition in the software industry from heavyweight engineering efforts to an almost sports-like scrimmage. Waterfall didn’tkeep up, they complain. Projects turned into congested pipelines and out of desperation to reclaim fluidity, the entire cycle broke down into an environment of iterative re-development that gave birth to Agile. Increasingly, developers collaborate in short sprints to rapidly address evolving concerns rather than as construction crews working from blueprints. What does this new era mean for technical writing as part of software development? More specifically, what is expected of an Agile Technical Writer?
To answer this question, let’s consider the question from a viewpoint that has not changed. To perform any act—software development included—one needs to know 1) what to do, 2) how it is going, and 3) when it’s done.
Knowing What To Do
An informed requirements artifact was compiled at the beginning of a waterfall project to address this issue. A synthesis of product development and technical expertise produced architecture documents. Yet requirements changed for many reasons, and the effort to maintain the role and usefulness of the requirements document grew too great. Lack of clear requirements became a dirge.
Whether converting a list of requirements to architectural components, molding a business idea into a functional process, or sketching a sleek user interface on a cocktail napkin, the overall goal of a software development initiative is to turn human ingenuity into electronic signal. The waterfall model called for extensive analysis in this initial phase considered as essential as the design prior to building a bridge.
Agile takes this exercise down a size and ups the speed, making requirements-gathering more like the wind-up for a pitch or the stride to the line in bowling.
Short descriptions and lightweight screen mockups and diagrams do the job. A writer who can sling these like a police sketch artist is quite valuable. So too is someone who can transcribe to a wiki from whiteboard scribbles. At this phase in the process, a writer is an on-the-scene reporter. Sound-bytes and snippets of information that persist from design-related discussions are key to maintaining something that the gate-keeping style of the waterfall requirement tomes did not: Continuity.
Knowing How It’s Going
Project tracking matrices followed pre-allocated labor, traceable to the requirements document through an architectural definition. The course of the project was charted in advance and everyone consulted the project plan as a point of coordination. But overwhelmingly, project-management-related documents showed two things if their accuracy was maintained: over-time, over-budget.
This area possibly suffers the most from failures in the other two. Without a useful requirements document and credible test plan, the traceability of labor broke down. As this breakdown continued, more effort was put into drawing the work along the path planned. Eventually, the industry lost faith in the development model before it resolved the underlying conflict. Whereas yesterday everyone approached the spyglass of the project tracking sheet for signs of progress that no one could see happening, today regular meetings raise signs of progress for the entire team to see. These so-called scrums are the primary means of communicating progress.
Documenting the work of an Agile development team is more like fleshing out the stories that are emerging on a reality show. The writer here plays the role of investigative journalist or even daytime talk show host. Flexible ticket-tracking applications streamline a lot of this. It’s these signals during the game that give the coach enough information to call the play.
Increasingly, technical writers looking to add value to the project-management aspect of an Agile development team will be called upon to organize tickets into hierarchies after-the-fact as a translation for financial departments. These writers will be responsible for drawing connections between events based on how they played out and when they played out. An engaged, alert technical writer will be successful. Again, allowing a continuous plot to emerge and elaborating on it ranks higher in value than writing the script from scratch before handing it to the actors.
Knowing When It’s Done
At the end of the project, QA ensured a useful product by testing it against the requirements according to test plans, and performed usability tests alongside planned user documentation. But even assuming the code came out correct, which it rarely did, this is where the waterfall model first broke into cycles of re-development with such regularity that it was the requirements that ultimately came into question.
As with other Agile themes, testing occurs on a much faster timetable now. The continual release of expanding features requires it. While test plans for individual sprints will continue to be useful, they will be less ordained in advance. Agile is joining the testability and instruct-ability of software development. The answer to “Is it done?” is less “If it passes the tests” and more “If it helps the user.” What this means, practically, is that a developer tests heavily as he or she works on smaller components at a time, produces some of the end-user material his or herself, and the instructional material and test plans become one.
Technical writers augmenting this part of the process will be sought after for their ability to collaborate in their own work. An ability to interact with developers has always been a strength of good technical writers. In the future, that strength will be tested.
Conclusion
A technical writer who can draw up the content of a blog about a new software application or tool while interacting with and querying the engineer in a brief conversation and with a few emails exchanged is a valuable asset, because that blog is functional as a progress marker, as a marketing tool, and as a statement of work. By joining the developer in a screencast walkthrough and linking to an open-source repository of examples, this documentation effort becomes a hub connected to technical specification.
Developers are taking more on themselves as part of an emerging culture of communication in their own community. A successful Agile developer values communication and is eager to perform it. He or she knows that communicating before and during a task eases its accurate completion. The new software workshop is not a row of quiet carpenters driven by a plan-wielding foreman. It is a team of independent but cooperative players, breaking across the field between huddles and making plays as they are called, not in the order they were documented in the playbook.
If the way Waterfall and Agile tackle the three fundamental issues we’ve addressed is any indication, then like the developer moving from the idea of highly directed craftsmanship to one of a collaborative artisanship, a successful Agile technical writer will be called upon to abandon the dying idea of building and guarding a monolithic document checkpoint, and join the team as a player who assists in every communication as it occurs.