Best practices for authoring end-user documentation in an agile environment

By Shweta Naresh on Writing docs from 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.

PLC phase	Work involved
Initiate	Evaluate the project’s goal, timelines, and costs Review the requirements and available resources Evaluate the tools, training needs, deliverables and so on
Plan	On-board resources Elaborate and communicate requirements Define acceptance criteria Identify the scope, risks involved, and so on
Execute	Allocate resources Build deliverables
Monitor and control	This phase is generally combined with the execution phase. As part of monitoring and control, the team: Constantly monitors progress Delivers smaller chunks Gathers data
Close	Deliver project Retrospective

The following table provides details of work that should be done during each CLC phase.

CLC phase	Work to be done
Research	Participate in PM-PO-Eng discussions Scan the documents from product management, if any Identify the touch points to address the business requirement Plan resources Identify training needs
Plan \| Estimate	Scan the design documents Analyze requirements Identify deliverables Scope and estimate the work involved Create a framework/content plan for the work involved Start coordinating with the stakeholders
Write \| Edit	Draft content Edit/revise content
Reviews	Track progress of the content plan Review whether all use cases are addressed
Publish	Publish content

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	Phases PLC \| CLC	Work to be done in CLC
Evaluate the project’s goal, timelines, and costs Review the requirements and available resources Evaluate the tools, training needs, deliverables and so on	Initiate = Research	Participate in PM-PO-Eng discussions Scan the documents from product management, if any Identify the touch points to address the business requirement Plan resources Identify training needs
On-board resources Elaborate and communicate requirements Define acceptance criteria Identify the scope, risks involved, and so on	Plan = Plan \| Estimate	Scan the design documents Analyze requirements Identify deliverables Scope and estimate the work involved Create a framework/content plan for the work involved Start coordinating with the stakeholders
Allocate resources Build deliverables	Execute = Write \| Edit	Draft content Edit/revise content
Constantly monitors progress Delivers smaller chunks Gathers data	Monitor & control = Reviews	Track progress of the content plan Review whether all use cases are addressed
Deliver project Retrospective	Close = Publish	Publish content

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!

Shweta Naresh

Shweta is a senior tech writer at Red Hat. She is passionate about delivering positive user experience through cross-functional team collaboration, and about creating visuals for illustrating complex concepts. When she isn't writing documentation, she can generally be found baking, yogging, or enjoying nature walks. You can connect with Shweta on LinkedIn.