Over the past several years, organizations have been adopting product development methodologies such as agile and lean in an effort to increase efficiency and minimize the delay between product releases. Such approaches are a natural fit in an increasingly cloud-centric and SaaS-focused world.
A key part of the transition from waterfall to iterative and incremental development is the formation of cross-functional teams, consisting of small groups of dedicated workers who can perform all aspects of product development, from coding to QA and, theoretically, documentation. Teams that follow Scrum, a common development framework, work in short two-week or three-week sprints and aim to deliver features that are “done” at the end of each sprint. Although the definition of “done” can vary, it usually means that the feature works, has passed through QA, and is documented.
However, real-world implementations of agile and lean tend to differ substantially from the theory, and nowhere is this clearer than in technical writing. When working with cross-functional teams, technical writers encounter several challenges:
- Documentation tasks are fundamentally different from other development tasks. In theory, any member of a cross-functional team can perform any of the tasks in the backlog. However, technical writing requires a different skill set than programming—ask anyone who has read documentation written by developers. Similarly, there are few tech writers who could seamlessly take on coding tasks. Writing tasks therefore tend to be isolated from the rest of development work and remain the responsibility of writers.
- There are usually more teams than tech writers. It is rarely feasible to dedicate a technical writer to each team on a full-time basis, yet according to Scrum, the product (including the documentation) must be releasable at the end of the sprint. How can writers deliver documentation if they cannot be fully involved in all development teams?
- Short development cycles leave little time for documentation. During sprints, development continues right up to the end of the sprint, which presents a difficult choice to writers: either begin documenting something unfinished and that may change, or wait until the end of the sprint and hope to cram in as much writing as possible. Neither option is appealing, nor are they feasible in the long term.
What can technical writers do when faced with such challenges? There is no perfect solution, but the following suggestions, alone or in combination, might help you adapt your writing practices to a cross-functional team environment.
Sprint + 1
One option is to adopt a “Sprint + 1” approach to documentation: begin documentation after the current development sprint is complete. This approach ensures that you will be documenting completed features and will not have to rewrite content and redo screenshots or videos due to last-minute changes in development.
However, this type of documentation ensures a delay between the completion of development work and the completion of documentation, so the team must be willing to change their definition of “done” to accommodate documentation.
Act as Service Providers
There are rarely enough writers in a company to act as dedicated members of all cross-functional teams. Instead, it might make more sense to think of technical writers as service providers involved with teams intermittently, similar to release engineering, marketing, and so on. Writers might be fully involved with a team for one or more sprints, then shift to another team as required. Alternatively, they might split their time proportionally among several teams on an ongoing basis, adjusting as necessary.
Front-load User Interface Development
If you are documenting tasks in a user interface, ask the team if it is willing to do UI work early during a sprint or series of sprints, assuming that such work is not dependent on back-end enhancements. Doing so can help writers get started as early as possible in the development cycle, which in turn makes it more likely that you will be able to deliver documentation when the feature work is complete.
Update Documentation Dynamically
Consider separating documentation from the product itself, and instead hosting it on a help website or customer portal. Divorcing documentation from product packages provides flexibility in making updates: if you cannot finish everything in time for a product release, you can update it as soon as possible afterwards and make incremental improvements that are not tied to product releases.
Obviously, separating documentation from products might not be feasible for all businesses. If you deliver printed guides, or customers keep their products on an internal network behind a firewall, this approach might not work for you.
Document Features, not User Stories
In Scrum, developers break features down into user stories, which can be quite granular and not particularly relevant for technical writers, who tend to think and work in terms of features. It may be most practical for you to intentionally separate documentation from the agile or lean process as much as possible, and develop a parallel feature-based process that works for documentation.
Such an approach means that documentation misses out on some of the benefits of scrum, such as metrics and velocity tracking.
Considerations
Documentation in cross-functional teams poses unique challenges, but there are solutions. As with any documentation practice or development methodology, you will have to tailor solutions to your workplace and teams, and of course ensure that you satisfy customer requirements. Regardless of your desired approach, be flexible, get buy-in from all stakeholders, and keep looking for ways to improve the process.
Aaron.
