In any agile project, there are pigs and chickens. These terms describe the level of involvement that any particular person has within a team. Pigs are those project members who are fully committed to the project and are accountable for its outcome. Anyone else is a chicken. Chickens might consult with the team, help remove blockers, or track the progress of the project.
These terms come from a story: Pig and Chicken. Pig and Chicken are walking along, and Chicken says, “Hey, we should open a restaurant together!”
Pig thinks for a minute and asks, “What would we call it?”
Chicken says, “I’ve got the perfect name! We’ll call it ‘Ham ‘n Eggs!’ ”
Pig replies, “No thanks. I’d be committed, but you’d only be involved.”
At Salesforce.com, we use our own implementation of agile. When the development teams moved to this methodology about seven years ago, we included all the standard functions: product owner, quality assurance, and development. At that time, the decision was made that end-user documentation would be a full part of the process. So here at Salesforce.com, tech writers are full stakeholders in Scrum teams. This results in two things:
1. Better documentation
2. A better product
There’s no mention of end-user documentation in the Agile Manifesto. By the same token, most books about software development using agile have little to say about how the creation of documentation and user assistance fits in the process. But like many aspects of agile, it’s left up to companies and teams to figure out how best to integrate these functions.
End-user documentation is often marginalized in the software development life cycle. But it shouldn’t be. Good documentation enables customers to solve their business problems with the software and figure out any issues they encounter. It creates tremendous customer goodwill, which although difficult to measure, is important to the adoption and continued use of a product. In many cases, user assistance can lead to a reduction in support costs; poor documentation tops the list of API worst practices in this article by Alexandra Weber Morales.
Better documentation
As the manifesto states, agile values “Working software over comprehensive documentation.” In this context, documentation means internal software development artifacts like functional specifications, technical specifications and design documents. This means that these internal documents can be very brief or non-existent, depending on the team. Typically, tech writers rely on this information to get an overview of the functionality and use it to document software, especially in the early stages when there’s very little to actually work with or look at.
This is why including tech writers in the full development process from the beginning is so important. This means that tech writers, whether they create content for end users, administrators or developers, are part of one or more Scrum teams. They participate from the very beginning in all aspects of the process. This includes attending sprint planning sessions, daily Scrum standup meetings, sprint reviews, and retrospectives. Tracking of documentation work can vary by team, but it makes good sense to create documentation user stories that are related to the original stories. At Salesforce.com, a feature isn’t “done” until the documentation is done.
This full involvement means that writers are in the loop and learn about features and functionality as they are being developed. Because user stories are based on tasks, writers can more easily write task-based documentation, which is consistent with agile on the whole: getting the right documentation to the user where and when they need it.
#!
In my experience, features can frequently come together in the later stages of a sprint, so having writers involved from the start means they aren’t starting the documentation at the very end of a sprint. The end result is focused, task-based documentation that the end user needs in order to use the software. This isn’t to say that there’s no creation of conceptual, reference or other types of content, but rather that minimalist principles are used so that just enough documentation is created.
Just like software, documentation is created iteratively throughout each sprint. The high level of collaboration that occurs in the agile process means that documentation is more visible; it gets seen by more people, more frequently.
When tech writers are full stakeholders in the software development process, it means that documentation is aligned with the principles of agile development: The information that users need is available when and where they need it.
Better software
When writers are involved in the creation of software from the beginning, they are able to provide input throughout the development cycle. For example, when developers create user interface elements, writers can provide usability feedback. Error messages, user interface text, and other elements can be reviewed by writers while they’re being developed.
Because writers document how a feature is used, they can provide insightful feedback from an end user’s perspective. The more experience a writer has, the more they can contribute to the design of the functionality being created.
This is much more cost effective than providing feedback after features have been created. Moreover, it’s much more likely that feedback can be incorporated early in the process rather than later, when the bar for modifications is much higher.
Including end-user documentation in the agile process is not without challenges. As a tech writer involved in writing developer documentation, I can say it’s difficult to write content early in a release when there’s very little to actually work with. In our environment, writers are typically on two Scrum teams or sometimes more. This can lead to balancing numerous meetings and intense context switching. That said, the benefits of this approach are well worth overcoming the challenges.
Ensuring that tech writers are fully integrated in the software development process means better documentation and better software. And that’s what agile is all about.
Dianne Siebold is a lead writer on the Platform Documentation team at Salesforce.com, and the author of “Visual Basic Developer’s Guide to SQL Server.”
