10 Tips for Technical Writers in an Agile environment
Most software development today occurs in an Agile environment. So what is it and what does working in an Agile environment mean for technical writers?
Most software development today occurs in an Agile environment. So what is it and what does working in an Agile environment mean for technical writers?
What is Agile?
In one sentence. Agile is a methodology characterised by the division of tasks into short phases of work with frequent reassessments and adaptations.
Here’s a super concise 3 minute video explainer if you like videos.
Fundamentally, Agile involves:
- Making a list of features you want (Product Backlog or User Stories)
- Sizing each feature up (Estimation)
- Prioritising features (Grooming the Backlog)
- Doing and delivering the work usually 2 weeks. (Sprint)
- Reviewing progress and updating the plan (Sprint review/Retrospective)
Key Agile Concepts
There are several key aspects to Agile. Scrum is the framework that provides specific rules and directions for an agile environment.
Scrum splits projects into bite size chunks, prioritises them and delivers them in short bursts called ‘Sprints’.
The Product Backlog is a list of all the desired tasks or features. These are also known as User Stories. These describe the user of the software, what they want to do and why.
Estimation Scores are allocated to each user story based on its estimated complexity. Estimation methods can involve powers of 2, the Fibonacci sequence or t-shirt sizes.
For example, using fibonacci scoring, a score of ‘0’ means the user story is very quick to deliver and there is no complexity e.g change font size in CSS.
A score of ‘8’ indicates a long time to deliver with high complexity and critical unknowns. It might take a couple of a weeks or more to delivery. Ideally this should be broken down into smaller tasks or issues with smaller point values and the complexities minimised.
Grooming the Backlog can happen once scores are allocated to issues. These can then be prioritised by the client or Product Owner based on their importance to the business. Priority issues near the top need to be fully defined before work can begin.
The Scrum team now decide on a sub-set of stories to complete in a limited period of time e.g. 2 weeks. These stories are put into a Sprint and these are the only issues focused on.
At the end of a Sprint, working software is the key measure of success.
A Sprint Review/Demo reviews what stories were completed and which were not. It demos the completed unit.
A Retrospective is an important part of the sequence whereby the team can reflect on what was done well and what could be done better. It is a great opportunity for team growth and and effectiveness.
Then the whole process repeats.
So how does a Technical writer fit into all this:
Technical Writing in an Agile environment
Documentation is treated like any other deliverable on an Agile project. It gets estimated, sized and prioritised like any other user story. So how do we as Technical writers ensure the docs keep up with current issues, upcoming feature changes and the general pace of delivery?
Proactively watch for and track down information
1. Ideally work in the same location as the scrum team. Talk to them, participate in ceremonies such as stand ups and sprint planning but be judicious in what meetings you attend.
2. Get involved in sessions where user stories are being formed as these can enable writing to begin on day one of the sprint.
3. Use the same chat service to track conversations and how they relate to the docs. It can be useful to review previous discussions that may have already taken place on such things as terminology.
4. Plug in to JIRA updates from developers. After a developer updates a spec, proactively get in touch to find out the impact on the docs.
Empathy for end users is №1
Staying connected to the needs of the target audience is paramount for technical writers. How well are the docs meeting their needs? What are their pain points?
6. It is super helpful to have a contact in Technical Support or Customer Services who knows what the recurring issues or pain points are. These can then be tracked and monitored. Ensure an open channel of communication with them.
7. Staying connected to Sales and Solution Engineers is super important from a wider business perspective. What are the client’s pain points. Can these be addressed via the docs without changing the software?
Get it DONE
The docs are an integral part of working software. From a tech writer perspective, a feature is not DONE if the docs are not complete. The docs are not done unless they meet end user needs.
8. Get involved with, or conduct usability studies and other user research studies. Speak to the UX team to conduct user testing of the docs.
9. Get new starters to test out the docs using user research techniques.
10. Assess success via webpage popups, chat rooms, user groups, online forums, conferences and direct feedback.
So, that was the 10 Tips for Technical Writers in an Agile Environment.
It’s an interesting area and a lot depends on the company and resources available. You can’t be in every scrum team if your company has twelve products and a team of one.
