A Technical Writer’s Journey to SAFE

low angle photo of volkswagen kombi
Photo by Alfonso Escalante on Pexels.com

Last year my company adopted SAFE, a new working methodology to enhance alignment, collaboration, and delivery for multiple Agile teams. We were all excited and curious about this new approach. SAFE would allow us to communicate better, anticipate bottlenecks and prevent unexpected dependencies that caused many issues in the past.

The documentation team was also eager to know more about SAFE. It would be the next stepping stone to optimize our involvement with the teams and raise the quality and user-friendliness of the documentation. SAFE would allow us to get accurate information earlier and to create a commitment plan to better manage our workload.

Although this methodology has proven to be very successful, we soon realized that it lacks information on how technical writers should interact with other team members and prepare for the PI, or the role they play during the event and on how to participate in the PI execution. In fact, the official SAFE site contains only one reference to technical writers: we are “potential members of shared services”. The trainers provided us with a lot of information on what to do and when, but these guidelines are missing from the official SAFE documentation.

During the last years, our team has come a long way to boost our visibility and the general perception of our value for the company. The progress has been remarkable. We are now present in all important meetings, collaborate regularly with all stakeholders and receive valuable feedback from support, pre- and post-sales, product management and end users on how to improve the documentation, and consequently customer satisfaction.

To make up for the lack of guidelines, we decided to define our own best practices to work in SAFE:

Step 1: The documentation for each PI plan is organized within a dedicated EPIC, and each task is linked to the corresponding DEV issue

Documentation is not a dependency for the development teams, it is part of development. During the PI planning, we identify which stories need to be documented and flag them. Then, we create a documentation EPIC and tasks for every story that requires documentation. Finally, we link the documentation tasks to the development tasks.

This approach has several advantages: on the one hand, the development teams know at a glance if documentation will be provided for a story, the progress of the tasks, and they can also review the new content by clicking on the internal link to the latest version of the documentation (included in the documentation task and only available for internal users). On the other hand, technical writers can keep track of the progress of the dev tasks and start working on the documentation as required.

Step 2: The documentation team is also a development team

Technical writers do much more than documenting features. We talk to customers, create training materials, curate texts, continuously improve/update existing information, work on standards and guidelines, help define UI text, review system/error messages, create videos and so on. On top of that, we document features for new releases and work very closely with development teams located in different countries. We also need to learn new things on a daily basis to keep up with development and describe processes and practices in the best possible way. All this effort needs to be visible.

To showcase it, we create a PI plan for the documentation team (which contains additional tasks from those created to document dev stories) and present it in front of all teams that are part of the release train. The time allotted for these “extra tasks” depends on the number of tasks created to document new features.

Step 3: Technical writers ensure message consistency

Technical writers act as gatekeepers for text quality and uniformity of the user stories. We work closely with the Product Owners and UX designers to help define the text displayed in the user interface. We suggest enhancements, proofread existing content and align the UI with the user documentation to ensure product consistency.

With these simple three steps we established our place in SAFE and successfully integrated and supported the teams to develophigh-quality software.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s