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.

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! 


About the author
Shweta Naresh
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.


On the go? Bookmark this article for later with Ctlr + D
Subscribe and get notified as new articles arrive
(No spam, pinky promise)