Best practices for authoring end-user documentation in an agile environment – by Shweta Naresh
Shweta Naresh | March 25, 2021
'Agile' has been a trending word for more than a decade now. Almost all major software enterprises now follow agile methodologies to execute their software development projects. While agile seems to have resolved a few pain areas for enterprises, for the project teams it has been more about introducing additional concepts, additional tools, and many challenges.
But has agile really introduced these challenges?
Based on my experience of working with agile teams for more than a decade now, I would rather say the challenges are often seen because the teams do not live up to agile principles, but focus more on using tracking tools and introducing scrums and stand-ups. Each involved team faces their own set of challenges, and being a technical writer in an agile environment is no cake walk. Your experience with the teams can make or break your days. If you are the lucky one, you can have fantastic teammates who don't forget to involve you in the work or get you the inputs in time. However, you can also be an unlucky one where no one gives you any input on time or does not involve you in the work, and this can be extremely frustrating because of the last minute surprises or slipping of timeline.
Whether you are the lucky one or an unlucky one, a few handy best practices for authoring documentation in an agile environment will definitely make you feel involved with the teams, in better control of your work, and as a cherry on the top, gain the trust of your teammates. It's no magic, just add a few secret sauces to your content development life-cycle.
Creating the secret sauces
A solution that addresses business requirements always makes a project successful, and each project team contributes a unique offering to develop the solution. We know that technical writers author product documentation as their contribution. Therefore, to execute a documentation project in an agile environment, it is important to understand how technical writers can function successfully.
We know every project has a life-cycle (PLC) with various phases. Similarly, for a documentation team, content creation has a life-cycle (CLC) too. The key ingredient in creating the secret sauces lies in connecting the CLC with the PLC, and not just creating the content itself. But before we dive into connecting the CLC with the PLC, let’s take a look at the various phases and what’s dealt in each of these phases.
The CLC and PLC
The following diagram depicts phases in a Content Life Cycle and a Project Life Cycle.
Before we take a look at how to map the CLC phases with that of the PLC phases, let’s first understand what’s dealt in each phase of both these life-cycles.
The following table provides details of work that is done during each PLC phase.
Monitor and control
This phase is generally combined with the execution phase. As part of monitoring and control, the team:
The following table provides details of work that should be done during each CLC phase.
Work to be done
Plan | Estimate
Write | Edit
Connecting the CLC and the PLC
Now that we know the various phases of PLC and CLC, and the work done during each of these phases, the success of authoring content in an agile environment lies in connecting the phases of both the life cycles.
The following diagram represents how the phases of both the life cycles can be connected for smart workways and better deliveries.
Connecting the CLC and PLC phases helps the writers to determine the work that writers can do during each phase, and to better structure the project assignments to reduce some stressful moments.
The following table maps the PLC and CLC phases, and the corresponding work that writers should be involved in:
Work involved in PLC
PLC | CLC
Work to be done in CLC
Initiate = Research
Plan = Plan | Estimate
Execute = Write | Edit
Monitor & control = Reviews
Close = Publish
The final take
If you notice, the phases from both the life cycles go in a circular fashion. Typically, when we talk about phases, we visualize moving from one phase to another till we come to an end of a flow. However, the agile workways bring in the difference here. In an agile environment, the planning, reviews, testing, deliveries are all done in smaller sprints and continuous manner. It is therefore essential to work hand-in-hand with all the stakeholders, and the key is communication!
Agile is an environment where we need to adapt to change, and deliver early and continuously.
To author end-user documents in an agile environment, writers need to get on-board right from the planning phase, and participate right from the planning activities. Yes, there would be a spike in the number of meetings that one would be attending, and your calendar would look bloated, but that’s the platform for your self-study, which helps you to gear up during the actual execution.
So, don’t fear the meetings, or the chaotic discussions, or the ever increasing number of sticky notes on the sprint board. Just stay patient with the team, and keep your tentacles on to absorb the discussions, voice out your understanding, list your questions and get them answered. I promise, you will discover so many more avenues to participate and to contribute, and discover a better communicator in you!