Single-Responsibility Principle for Technical Documentation

What this article covers

A customized application of the single-responsibility for on technical writing. Tools

N/A.

Overview

According to Wikipedia, the Single-Responsibility Principle (SRP) is:

This term was created by Robert C. Martin who expresses the principle as:

"A class should have only one reason to change."

The word "reason" caused some controversy within the community, so he had to provide further clarification, saying that the "principle is about people." He also added that the principle's focus is roles or actors.

Roles in a Documentation Project

Documentation projects may include the following roles: collaborators, editors (reviewers), technical writers, translators, and managers. Ideally, we'll have a single person for each role.

Lucky for us, we have technical writers, a role that absorbs many of the previous roles. Technical writers:

• Edit the collaborations with other team members.

• Manage the documentation project and platform.

• Collaborate with new content actively.

Having a technical writer allows your collaborators (Subject-matter experts) to focus where they provide more value:

While Subject-mmatter experts provide a draft with the right information, the technical writer converts their information drafts into content.

But how do we apply and support this separation of responsibilities?

Single-Responsibility Principle (SRP) for Documentation Projects

Applying the SRP to documentation projects requires a shift in the product team's mindset:

• Team members or collaborators provide the information.

• The technical writer creates the content.

Key Concepts

Applying the SRP to documentation projects involves understanding the key concepts described in the following table:

Concept	Description
Information	All pieces of text, screenshots and raw data provided by collaborators. Text includes introduction, process steps, features, and code elements (libraries, parameters, snippets, endpoints). Information is provided as a draft containing the right informative elements, in the right order and in the right context.
Content	Information that has been standardized according to the style guide, Information Architecture and technical writing best practices.
Shared Ownership	Documentation is a team effort, with everyone contributing to and owning the final result. The visible face of the documentation set is the Technical Writer.

With these concepts in mind, we define the following roles and responsibilities:

Role	Responsibility
Collaborators	Provide information that is: Correct Presented in the right order Embedded in the right context
Reviewers	Validate the information provided by collaborators when required.
Technical Writers	Convert information into content Manages the release process Creates content from scratch Manages documentation as a product

Conclusion

The single-Responsibility Principle is the new mindset of assigning a limited and specific set of tasks for all the roles participating in the documentation workflow, ensuring everyone adds value according to their expertise, and embracing documentation as a shared ownership to provide documentation we are proud of.

The Single Responsibility Principle (SRP) changes the concept of documentation ownership from individual ownership to shared ownership. Now, all product development roles can contribute to the final product: we all own the docs!

While this shift to shared ownership may be challenging for some, technical writers can ease the transition with effective communication strategies.