We all are pretty much aware of a technical writer’s role in the software industry. Typically, a technical writer performs the following:
- Determine the needs of the end-user with respect to technical documentation
- Interact with product developers, designers, and SMEs
- Write end-user documents and organize support documents
- Prepare user guides, manuals, training videos, technical papers, and so on to increase the user’s understanding
While performing the aforementioned tasks, the writer plays various roles and helps enhance the product quality. The following are some of the phases in an agile environment that more or less every product goes through. While every project has its own protocols, I have tried to map the generic ones.
Product Design Phase
During the product design phase, the role of a writer revolves around:
- Understanding the requirements
- Analyzing authoring tools and output formats
- Understanding the style guide(s)
- Preparing document prototypes
- Creating a pilot for the document deliverable
The project team is engaged in:
- Designing the product architecture
- Planning UX
- Preparing wireframes
- Preparing testbed
In this phase, other than their primary roles, writers bring out their design skills. They help improve the UX design by sharing comments as the first end-user of the product. They provide suggestions in crafting the UI text and entry-level product improvements. At this point, a writer often applies the following words by Mark Twain while reviewing the wireframes:
Writing is easy. All you need to do is cross out the wrong words.
Estimate, Evaluate, and Contribute
I often call this the EEC phase. The sprint plan and tasks would be in place by now and writers have the document requirements added to the sprint plan as well.
Writers must make sure that they add every task, such as the following, to the sprint plan:
- Understanding feature
- Hands-on with the feature
- Preparing template
- Preparing first drafts
- Incorporating review comments
- Self-review and editorial review
This not only helps plan tasks and estimates beforehand but also makes the sprint team aware of how important it is to have the documentation team working alongside them right from project kick-off.
In this phase, as there is not much to document, the writers step into the shoes of an end-user, by getting hands-on experience of the developed feature. Often, they capture unnoticed areas/issues while the QA team is focusing on preparing the testbed and testing technical aspects of the product. Feedback from writers helps eliminate the first level of change.
Initial Product Demo
At this point, when the project team has prepared a feature or two for the demo, the writers are ready with a structure (TOC) of the technical documentation, with a few developed features documented. It’s best to go ahead and share the document with the stakeholders for an early review. Make the stakeholders aware of the document flow, usability, and end-user experience. Getting feedback in the initial stages would need minimal rework; saving a lot of time. Utilize this time for other activities.
Sending smaller chunks of drafts for technical review will result in getting quicker reviews. Remember, the smaller the chunk for review, better the comments and the quality of the documents.
It is often said – “Block by block you can build a beautiful mansion”. The same applies to a perfect document as well.
Openness to the scope of defects, feedback, change requests, surprise feature additions, improvements will help you deliver a perfect document. Hence, the design of the document must be excellent to accommodate all such changes.
Categorize and Align
At this stage, the product development has kicked off, the developers are busy writing their code, QA testing the features, and writers are preparing drafts.
Best practice suggests defining deliverable priorities by listing them, the content scope of each document, the delivery dates and output formats, the SMEs, and so on.
Listing priorities helps in tracking and raising flags for any dependencies. As the development and QA tasks are mapped to scrum sheets, it’s recommended that writers also tag their tasks. This way, their tasks would not only be tracked, but they will also be able to complete them smoothly. Dependencies such as not receiving inputs or reviews from SME can be flagged, ensuring a quick turnaround time for the document.
Remember to tag the documents to software builds as shippable items and maintain the versioning of the documents as followed in the build. This helps in mapping the documents to incremental builds.
In parallel with the documentation tasks, the writers also review the product and provide comments for UI consistency, appropriate error messages, UI labels, help texts, and so on.
Connecting People
Attending daily scrums is an added advantage as the writers would be aware of the project progress, feature development, testing status. They can also gauge their tasks, be more aware of blockers/exceptions, etc. that need to be addressed in the documents. Also, it’s the right place to raise concerns if any documentation dependencies arise. Concerns raised in this platform are quickly addressed.
It’s now time for the writers to turn into technical communicators and reviewers. At this stage, they can review UI literals, readability of logs and error messages, product navigation, design documents, test plans, etc. This not only increases the value of the product, but also helps bring all stakeholders on the same page—be it the developer, the architect, the QA, or others. In addition, the writers can get involved in release audits and end user testing.
A technical writer’s main role is writing technical documents, but they do don a lot many hats, as shown in the image below.
