More than just docs – the added value of tech comms in an Agile world
Twelve years ago, when I began my career in software, I didn’t fully appreciate the impact that my first technical author role would have on me. I started out in a company that had fully embraced Agile software development. Myself and half a dozen other technical authors were each embedded within a multidisciplinary development team. I worked alongside designers, user researchers and product marketing specialists as well as developers, testers, product managers and project managers. In doing so, I experienced first-hand the value of shifting tech comms to the left, but I didn’t have much to compare it against.
Since then, I’ve worked in a range of different environments: from teams at the start of their Agile journey to experienced teams combining both Agile sceptics and purists; with Kanban, Scaled Agile and XP; and in organisations claiming to be Agile because they have sequenced a waterfall project plan into “sprints”.
Through it all I’ve come to appreciate not just the benefits that Agile offers to software development in general, but also the extent to which embedding writers in an Agile team and developing documentation iteratively, alongside the software itself, enhances the whole product.
Enabling outcomes while delivering outputs
When technical writers are involved in the day-to-day activities of building a software product or service, we accumulate a detailed understanding of the technology, the user needs and the business goals. This knowledge is vital for the documentation deliverables, and working in tandem with the rest of the team means these help materials can be included in usability tests, alpha releases and early access programs.
This is all good, but it’s only one half of the equation. In my experience, the process of drafting documentation produces further insights that can be fed into the design and development of the product or service to create a better solution overall.
Let’s look at how that works with specific types of technical content.
Conceptual overviews
Most help documentation will include some kind of overview that helps the user to understand what the software offers and how it works. Drafting this kind of content requires writers to examine the mental models on which the system is based and how they apply to the target audience’s context of use.
If that model is not applied consistently or is too far removed from the target users’ perspective, the product or service becomes harder to use. Drafting this type of content during the early stages of development means there is more time for the team to adjust the design and create a better experience for users.
User guides and tutorials
These address particular user goals and provide step-by-step guidance on completing specific tasks. In planning and drafting a user guide, a technical writer goes through the entire user journey in detail – reviewing each step in the product, identifying any external factors that a user would need to consider, and exploring what happens if you stray from the intended workflow.
By going through this process, technical writers often identify opportunities to refine the user experience. There might be an aspect of the UI design that could be streamlined or a control that would benefit from some embedded assistance. On more than one occasion, I’ve asked questions that resulted in the team modifying the default behaviour or identifying steps that can be handled “auto-magically”.
API references
While reference material might sound like the kind of content that could easily be left until the software is ready to release, there’s a clear case for developing API references at the same time as the software.
Doing so helps the team to consider how the target audience will use the API and which mental model will make sense in their context of use. From this you can devise the structure, endpoints and parameters that will best support your users’ needs.
The bottom line
The advantages of shifting left – that is, moving activities that were traditionally performed later in the development process to an earlier stage – have been discussed widely in the context of building and testing software. In my experience, the same applies to documentation. When technical writers are embedded within a software development team, the benefits go far beyond the creation of good quality, timely documentation.
Writers bring another perspective to the mix and our work creates yet another regular, rapid feedback loop. These insights provide opportunities to improve your product or service design, and the earlier they are available, the easier it is to act on them. As with many aspects of Agile, the key is in fostering a culture of open communication and collaboration in which the team can iterate towards the best solution.
