Eric Sedor is a senior software engineer at MongoLab, a cloud-based database provider located in San Francisco, and frequent contributor to The Technical Reader. Eric cut his technical writing teeth at Shoap Technical Services before returning to his true passion, software engineering.
For additional information regarding Waterfall/Agile development and how it impacts technical writing, please refer to previous blog posts written by Eric Sedor and Shaun Kelly.
Moving a product out the door to capitalize on market demand is a necessity – it’s simple economics! Consumers demand constant product improvements. This “out with the old, in with the new” mentality has led many successful companies to switch from Waterfall development to Agile. What does this mean exactly? For the uninitiated, use this simple analogy. Waterfall development can be compared to a marathon. All software features are built in one long process and then errors are fixed. Agile development is more like a series of sprints. Software is released in a series of small iterations. Each release includes a few added features, and errors are corrected along the way rather than at the end. As you can imagine, the switch to Agile development completely shatters the status quo and roles of people associated with the development teams. This led us to wonder: Specifically, how does the switch to Agile impact the role of technical writers?
“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?
The Work Management Process is an initiative of one of our clients to standardize the process of work identification, planning, and completion at power plants the Company owns and operates. This process aims to transition work activities at power plants from a reactive to a planned mode, thereby improving asset reliability and lowering costs.
The purpose of this training is to present an overview of the Work Management Process either as a refresher for existing employees or as an introduction for new employees.
The training is broken down into six lessons, each of which correspond to a particular step within the Work Management “Wheel.” Unlike a training course delivered via a learning management system, this training is completely open-ended so learners are free to explore and learn at their own pace.
Although this training is open-ended, some managers wanted their employees’ progress to be tracked to test their mastery of the content. Learners can directly link to a short quiz stored within an online learning management system from the Work Management Process Training site.
Goals and Objectives
The original Work Management Process Training existed as a 180-page document that learners had to read. Once our Technical Communications project team got our hands on that, we all recognized that we had an opportunity to create a unique eLearning experience from this training.
The primary goal of the training site is to create an interactive, online resource that employees can visit to learn about the Work Management Process. Using a simple design, contextual links and actions, drill-down exploration of content, and leveraging interactive learning experiences, our training site easily stands out as a technology-based learning site unlike any other training initiatives we have created in the past.
… we have come to value … working software over comprehensive documentation…
We don’t do a lot of work with practitioners of agile methodologies. I think that’s partly because there’s some built-in hostility towards documentation in the values of agile development. Of course, while the Agile Manifesto is referring mostly to documentation for the front end of the cycle (i.e., the giant FRS), that hostility ends up spilling over to end-user documentation as well. (I don’t think that was the intention.)