The Role of Technical Writers in Agile Development Teams

By /

The Role of Technical Writers in Agile Development Teams The agile methodology is part of the project management process and is mainly designed for software development. Demands and solutions evolve through self-organizing and cross-functional teams, their customers, and a collaborative effort. However, this methodology does work fine in technical writing. Technical writers are part of every software development team working on a project or product with a customer-facing component. Whether you are developing an essential UI-based tool for unsophisticated customers or an API with complicated parameters, even an accomplished developer would find it challenging to work with a technical writer to bridge the information gap between your development team and the end user. How would you incorporate a technical writer into your agile development? What role(s) does the technical writer play within the development team at your organization? In this post, we cover some tips on how to do just that. Scrum and Planning Meetings Technical writers are often outsiders in an engineering environment. They are usually outnumbered by engineers and work with several engineering groups simultaneously, making them easy to view as an entity outside of the scrum team. However, that perception only considers some hats a technical writer must wear. The technical writer is more like an embedded reporter, telling stories about projects the Scrum team(s) is working on. Those benefit from having details, at least not only about what it is but also what decisions went into creating it. This would enable the writer to explain better the benefits and snags of having a feature with one set of parameters created rather than another. Consider bringing the technical writers into the scrum meetings, especially at the planning session when the project has been conceptualized. This will not only provide much-needed context to the writer but will also save your team time explaining those details later on. 1. Location One standard mistake organizations make in their office layouts is to group technical writers with marketing, design, etc., and sit them with those teams away from the engineering department. Consider seating your technical writers with the engineers in an in-person working environment. Physically separating them prevents the writers from hearing and absorbing the day-to-day discussions that happen, often resulting in missed opportunities for documenting changes as they occur. 2. Development Environments The technical writers must have the same development/test environment as engineering. Even if it is a local deployment of the nightly build, the opportunity to explore and see code in advance of the documentation required gives the writers a lot of head start on their work. The better the documentation is, the more time the author has to use and document the upcoming release. This also allows technical writers to fulfil their often vital role: testing. Writers will test their documented steps to document a new feature. This allows them to find bugs in their documentation, usually in the code and product before launch. 3. Time A very valid commodity for any professional's day is time. Setting aside time for the technical writer to interview the team members is crucial for good documentation. It not only allows the writer to ask questions to better understand the product, but it also allows your team to catch and correct any inaccuracies in the documentation before it gets published. Product managers, project managers, engineers, and architects need to block out time with technical writers to review any major new release. This can involve directly checking the documentation drafts or just a sync with the writer to go over any forthcoming changes that they need to be aware of. 4. Forums and Chat Channels Engineering scrum teams primarily work with large teams and provide them with a private channel through which they can constantly interact outside of face-to-face interactions. These could be internal boards within your Khoros Communities site, team chats, issue trackers, shared virtual whiteboards, and collaborative documents. This is a great way to keep the technical writer informed about what the team is working on and if changes are in the works that may require additional documentation. It also allows them to ask questions outside of scheduled meetings and emails that can be quickly answered without having to set aside a set time. Documentation in an Agile Development Cycle As I say so often, those days when technical writers wrote documentation using Microsoft Word or any other static word-processing tool are gone. Nowadays, a technical writer has to be adaptive and agile; there is no other practical way, and that is provided only with the help of a help authoring tool. Still, not all tools are suitable for agile tech writing. Let's see what features a HAT should provide to help you keep up to date: 1. Reusing of the content: For example, you need to reuse one topic in different projects. Of course, you can copy-paste the content, but it is inappropriate even if your team is not agile; imagine how much time you will spend on this task. A HAT should provide features that allow you to do that with just one click. 2. Context-sensitive help: Your documentation and the product itself will become friendlier; sometimes, there is no need to switch to another web or application just to see the information you need. Context helps you make yourself, but some modern HATs can automate even this process. 3. Publishing on the fly: A HAT shall offer the possibility of publishing separate help topics as soon as they are ready without waiting for all of them. 4. Single-sourcing: In such a case, the possibility of single-sourcing is essential so that you do not have to copy and paste your content to create different outputs for different audiences. Summary In Agile, the technical writers do not just document; they wear multiple hats: engineering, quality assurance, product management, and documentation. As you see, agile technical writing is about teamwork and good help authoring tools that will allow you to carry out tasks faster. Technical writers are a rare breed in any organization. While usually not themselves engineers, they generally do better being thrown among them.

The Role of Technical Writers in Agile Development Teams

The agile methodology is part of the project management process and is mainly designed for software development. Demands and solutions evolve through self-organizing and cross-functional teams, their customers, and a collaborative effort. However, this methodology does work fine in technical writing.

 

Technical writers are part of every software development team working on a project or product with a customer-facing component. Whether you are developing an essential UI-based tool for unsophisticated customers or an API with complicated parameters, even an accomplished developer would find it challenging to work with a technical writer to bridge the information gap between your development team and the end user.

 

How would you incorporate a technical writer into your agile development? What role(s) does the technical writer play within the development team at your organization?

In this post, we cover some tips on how to do just that.

Scrum and Planning Meetings

Technical writers are often outsiders in an engineering environment. They are usually outnumbered by engineers and work with several engineering groups simultaneously, making them easy to view as an entity outside of the scrum team. However, that perception only considers some hats a technical writer must wear.

The technical writer is more like an embedded reporter, telling stories about projects the Scrum team(s) is working on. Those benefit from having details, at least not only about what it is but also what decisions went into creating it.

This would enable the writer to explain better the benefits and snags of having a feature with one set of parameters created rather than another. Consider bringing the technical writers into the scrum meetings, especially at the planning session when the project has been conceptualized. This will not only provide much-needed context to the writer but will also save your team time explaining those details later on.

  1. Location

One standard mistake organizations make in their office layouts is to group technical writers with marketing, design, etc., and sit them with those teams away from the engineering department. Consider seating your technical writers with the engineers in an in-person working environment. Physically separating them prevents the writers from hearing and absorbing the day-to-day discussions that happen, often resulting in missed opportunities for documenting changes as they occur.

  1. Development Environments

The technical writers must have the same development/test environment as engineering. Even if it is a local deployment of the nightly build, the opportunity to explore and see code in advance of the documentation required gives the writers a lot of head start on their work. The better the documentation is, the more time the author has to use and document the upcoming release. This also allows technical writers to fulfil their often vital role: testing. Writers will test their documented steps to document a new feature. This allows them to find bugs in their documentation, usually in the code and product before launch.

  1. Time

A very valid commodity for any professional’s day is time. Setting aside time for the technical writer to interview the team members is crucial for good documentation. It not only allows the writer to ask questions to better understand the product, but it also allows your team to catch and correct any inaccuracies in the documentation before it gets published.

Product managers, project managers, engineers, and architects need to block out time with technical writers to review any major new release. This can involve directly checking the documentation drafts or just a sync with the writer to go over any forthcoming changes that they need to be aware of.

  1. Forums and Chat Channels

Engineering scrum teams primarily work with large teams and provide them with a private channel through which they can constantly interact outside of face-to-face interactions. These could be internal boards within your Khoros Communities site, team chats, issue trackers, shared virtual whiteboards, and collaborative documents.

This is a great way to keep the technical writer informed about what the team is working on and if changes are in the works that may require additional documentation. It also allows them to ask questions outside of scheduled meetings and emails that can be quickly answered without having to set aside a set time.

Documentation in an Agile Development Cycle

As I say so often, those days when technical writers wrote documentation using Microsoft Word or any other static word-processing tool are gone. Nowadays, a technical writer has to be adaptive and agile; there is no other practical way, and that is provided only with the help of a help authoring tool. Still, not all tools are suitable for agile tech writing. Let’s see what features a HAT should provide to help you keep up to date:

  1. Reusing of the content: For example, you need to reuse one topic in different projects. Of course, you can copy-paste the content, but it is inappropriate even if your team is not agile; imagine how much time you will spend on this task. A HAT should provide features that allow you to do that with just one click.
  2. Context-sensitive help: Your documentation and the product itself will become friendlier; sometimes, there is no need to switch to another web or application just to see the information you need. Context helps you make yourself, but some modern HATs can automate even this process.
  3. Publishing on the fly: A HAT shall offer the possibility of publishing separate help topics as soon as they are ready without waiting for all of them.
  4. Single-sourcing: In such a case, the possibility of single-sourcing is essential so that you do not have to copy and paste your content to create different outputs for different audiences.

Summary

In Agile, the technical writers do not just document; they wear multiple hats: engineering, quality assurance, product management, and documentation. As you see, agile technical writing is about teamwork and good help authoring tools that will allow you to carry out tasks faster. Technical writers are a rare breed in any organization. While usually not themselves engineers, they generally do better being thrown among them.

Scroll to Top