Agile methodology emerged in the software development industry in the early 2000s. Many software development projects in the 1990s either failed, exceeded budget or were late. Agile methodology was a response to this trend.
Thorough analysis brought them to the conclusion that the method they used was in cause. Back then, projects were defined and planned early on. Team members agreed on their respective tasks, and went on to developing software which they only tested at the end of the project. This method left no room for adjustments or changes while the project was ongoing.
Experts thus needed to change the way software was developed into a more flexible approach that entailed increased collaboration, discussion, and feedback at the beginning and throughout the projects.
Today, agile is widely adopted in the industry. Although some software engineering departments claim to follow agile principles, many in fact only use a few of the tools it provides, leaving teammates – including technical writers – behind.
This blog will provide some tips and tricks on how to organize your work and team in the agile world, and how to avoid common pitfalls.
The Basic Principles of Agile
In 2001, the Agile Alliance was formed by partisans of a new methodology who published the Agile Manifesto which defines it.
- Individuals and interactions over processes and tools
Agile invites software development teams to focus on the people working to develop the product rather than the set-up to allow fluid workflow with discussions, reviews, and changes as needed.
- Working software over comprehensive documentation
Documentation must not be left out, but it needs to be relevant and written for the target audience, whether it is technical documentation or end user documentation.
- Customer collaboration over contract negotiation
Talking things over applies to teams working together, but also with customers to ensure the result fulfills requirements.
- Responding to change over following a plan
The principles listed above allow one to make adjustments when appropriate.
Here are some of the basic principles of the Agile Manifesto.
- Incremental development
Incremental development is one of the key principles of the Agile Manifesto. The method consists of establishing top level requirements to prioritize what should be in the software.
Work is organized in sprints or iterations, meaning developments is broken down into smaller time periods over several cycles until the end of the project. Each sprint includes development, testing, reviewing, and documenting a feature.
At the end of cycles, everything that started with the iteration should be completed and ready to be delivered to customers. Progress is measured in terms of functioning software.
- The team
At the core of agile stands a cross-functional team of developers, QAs, product people, technical writers, UI and UX designers who agree on how much work they can accomplish in one sprint, and commit to finishing it by its end.
- Transparency
Team members should, at all times, know where other members and the overall project are standing.
Transparency gives everyone an overview of the project advancement, and makes it easier to estimate completion time. It can be achieved with tools such as ticket systems, JIRA, and digital or real-life boards with stickers.
This further emphasizes the methodology of agile where change is perceived as part of the process of continuous feedback, rather than as an error.
Agile Methodology in Practice: Scrum
Scrum is the most popular agile methodology.
The sprint starts with the product backlog. It gathers the list of top-level requirements for the user. The product owner knows what users are seeking to achieve. They prioritize user stories, assign them to teams, and determine whether a user story is accepted and completed.
An epic is a bigger user story that is broken down into smaller user stories, then assigned to development teams to be finalized in one sprint. The definition of done (DoD) is a tool that lists all activities required for each story.
At the beginning of the sprint, everyone involved –including the product owner and the scrum master— come together for planning. They decide how long the sprint will be, which is generally inferior to 4 weeks to maintain agility.
The scrum master plays an important role by supporting the team to stay in track and fulfill their goal. They ensures things go smoothly, and that acceptance criteria are met by organizing meetings(among other things).
There are regular meetings during one sprint. The daily scrum (or stand-up), which is not necessarily every day helps teams organize and debrief.
Towards the end of the sprint, the sprint review is a demo to show the result. Everyone can attend, from the people who work in the team, to other members of the company, and sometimes customers depending on the company culture.
The retrospective is a different meeting that aims at looking back and analyzing what went well and what didn’t. Actions to improve workflow are then taken.
At the end of the sprint, we get a product increment – a piece of functioning software – that can be delivered to customers.
What Challenges Do Company Face in an Agile Set-Up?
In an agile setup, technical writers can become frustrated, especially when teams fail to follow the communication and transparency principles of agile. Below are some of the most common obstacles technical writers face, and how to tackle them.
Input challenges
Oftentimes, technical writers will report that they do not receive any input from developers, which makes it hard to write documentation.
Good user stories, including the user’s wants and motivations, can help technical writers drive a topic for the documentation. As they are used to thinking like a user, technical writers can assist the product owner in writing user. Sketches and wireframes also come in handy to give a better idea of what the feature looks like.
Moreover, documentation should appear in the definition of done list. Even though tech writers can’t realistically finish writing the documentation within one sprint, with the contribution of developers to prepare it, they are better equipped to get it done in time.
Meetings are a good way to receive input. Technical writers can get information, ask questions, and provide feedback to developers. They can also schedule interviews with team members.
During sprint reviews, technical writers get a better understanding of how a feature works, especially when they don’t have access to the product. Finally, if the company hosts usability tests, they can observe new users, and improve their documentation accordingly.
Time challenges
Engineers should ideally stop coding a few days before the sprint ends for the team to stay on track. They can use this time to give input to QAs and technical writers. This makes it easier to review or redo things if errors are detected.
Technical writers who have access to the necessary specifications can start writing ahead or while implementation is being done. If this isn’t an option, using larger increments for publishing can help reduce pressure.
The longer documentation is delayed; however, the higher the risks for inaccurate or out of date information. Input from SMEs becomes hard to obtain and there is little time to finish tech writing before the product is delivered to customers –there is no time for translation either.
Working with unstructured frame makers where publishing involves many manual tasks will further delay technical writing. It is then critical to optimize your infrastructure.
Meeting challenges
Technical writers often work with many teams. As a result, they have lots of meetings to attend, in addition to their tasks aside scrum related ones.
When possible, they should limit the number of teams they’re working for or skip some daily scrum meetings. Another clue is to designate a proxy, the scrum master for instance can take notes and share all the relevant information with them later.
More importantly, each team should find out what methods works best for them.
Translation challenges
In iterative translation, modularized content must be a requirement. Tools such as MadCap IXIA CCMS offer it, along with workflows for translation. In addition, the user interface must be localized before going into translation.
Other instruments to control terminology and check language are helpful to deliver quality and consistent content, which should also be a priority for translators.
Ways to overcome translation challenges include dropping the requirement to finish translations at the same time as the source material or remove translation from the agile process altogether. In all instances, translation should wait until there is enough material available. In addition to maintaining consistent and quality content, this prevents frequent changes and exorbitant translation costs.
Here are a few additional recommendations to make the best of agile methodology:
Team recommendations
In an agile set-up, technical writers should always be part of scrum teams. This will give them access to the input they need and the people they need it from. The team will also benefit from the expert feedback of technical writers and their user-centric point of view.
Infrastructure recommendations
Automated generation of output, version control and automatic builds are crucial to the system to separate the layout from the content, regardless of the tool technical writers use to write documentation.
Web-based reviews are more efficient and considerably facilitate. Markdowns are also a good idea when engineers and SMEs are involved in the process.
Working in an agile environment requires constant communication to be efficient. As they become complete members of the team, technical writers get direct access to developers and other teammates for input. Their own expertise will also benefit the team towards a successful project with fewer frustrations involved along the way!
This blog was originally presented as a IXIAtalks webinar by Marion Knebel from parson. You can find the webinar here.
Learn more about our IXIAtalks webinar series.
