The role and potential of Technical Writers in agile development

A little bit about me

I’ve been working as a Technical Writer at Kentico (Xperience division) for over 10 years. During this time, I believe I’ve come to know the product quite well, helped many customers and coworkers, and hopefully contributed to the overall development of Kentico and its products. I’ll try to use this article to share what has worked for me, and give some tips and recommendations.

Technical writers at Kentico work with their development teams very closely, have access to the source code, and attend all related meetings, calls, etc. My recommendations are biased by my personal experience at Kentico, but I believe everyone can adapt and find the right path within their own working environment.

Integrating into the team

When starting to work with a team of developers and engineers, a technical writer is often a bit of an outsider. They usually have less technical knowledge, and sometimes a different background and overall personality type than the rest of the team.

That’s why it’s extremely important to integrate into the team as much as possible, and build up trust and a strong working relationship with the developers. In an ideal scenario, both sides should respect each other’s knowledge and be completely comfortable cooperating. Developers will usually have deeper knowledge of the code-base and implementation details, but with effort, technical writers have the potential to serve as subject matter experts with the broadest knowledge of the team’s products.

As the first step, you need to truly get to know the surface-level parts of the team’s product and all related documentation. After that, the rest should come naturally with time. In my experience, the best way to connect with the team is to take an interest in their work and problems, help in any way that you can, and always keep on learning.

Writing the docs

Once you’re familiar enough with the product, you can start actually documenting features. Always try to think from the point of view of your product’s users. Depending on the subject you are documenting, that can range from a non-technical end-user to developers consuming an API or implementing customizations. You’ll bring a fresh perspective, because developers sometimes have trouble viewing their product objectively, with a slightly internal and technical bias.

Experiment a bit with every new feature, try various scenarios, and come up with examples for your documentation. Whenever something doesn’t seem easy or smooth, discuss it with the developers. If possible, try to find an easier option and suggest changes to your team. If it’s not possible for whatever reason, you’ll at least learn why the obstacle exists, and can document it accordingly. If you ran into a problem, chances are that customers reading the documentation will want to know about it.

You might sometimes feel more like a member of the QA team, but that’s fine. As most people in the documentation field know, actual writing takes up only a very small part of a technical writer’s time.

When consulting technical topics with developers, it's normal to not understand everything. But try not to tune out or derail the conversation. It’s always better to let the information flow, note down unclear things, and research them at your own pace after the discussion is done. The next time you discuss the topic, the conversation will be easier and quicker.

Most teams also have some form of review process for the documentation. Make it as easy as possible for team members to review your docs. It helps to prepare detailed descriptions for your tasks so that people can easily see what to read and what to focus on. They'll be happier, and do a better job if they don't have to struggle finding your changes or going through tons of "mindless" updates.

The main point of technical reviews is to validate the correctness of the information. Listen to all types of feedback, but focus on things like the overall structure, understandability and linguistic details. These are your domain. If you need a second opinion, do another round of reviews with your writer coworkers.

Giving a helping hand

At Kentico, we believe that everyone should do whatever they can to help their customers and coworkers, regardless of their role. Technical writers have a fairly unique position that allows us to view the product from all sides, and contribute in significant ways. You don't just need to focus on "language things", such as the documentation itself or captions and copy in the product UI.

I’d strongly recommend using your knowledge to help coworkers with their issues whenever you get the chance. This includes members of your team, support staff, or anyone else in the company. As mentioned, having a strong relationship with your team is critically important. When you consistently help people with issues, it builds trust and they’ll be much more inclined to help you in the future. Ideally, developers should feel confident that you have valid and informed opinions, and that you won't waste their time.

The key is to always pay attention and listen to what’s going on in the team. After some time, you'll find that you often know the answers to problems that are being discussed. And even if you can’t help, you’ll gain important context, and learn a lot about things you’ll probably end up documenting at some point.

If you have the time, offer to help with any team tasks that you feel you can handle well. Here are some ideas from things that I’ve tried in the past:

• Presentations to the company, support staff, partners or customers. You might actually be better suited for it than anyone else in your team.
• Testing of tasks or other QA work in general. You can use your breadth of knowledge to submit high-quality issues with detailed descriptions.
• Training new team members.
• Answering escalated support questions.
• Monitoring and screening of issues or tasks assigned to your team. Use your knowledge to add comments with reasons for the reported problems or potential solutions (often found in the documentation).
• Fixing simple defects or bugs. Make sure you know the correct processes first of course.
• Implementing minor improvements to the product that you think will help customers.

Participating in meetings

Meetings are a place where an experienced technical writer can really shine. For us it’s usually meetings related to agile development, such as backlog grooming, planning of development iterations, reviews of completed functionality, etc.

Always try to give your opinion and perspective. When discussing new features and planning your team’s future work, try to think of related edge cases and "gotchas" that were documented in the past, but many people will have forgotten about. And always keep your product consumer point of view.

During feature or iteration review meetings, think about how changes or new features could affect your documentation and impact customers. Whenever something is unclear or potentially problematic, let yourself be heard and ask clarifying questions. Make notes about things that could be added or improved in the documentation. Personally, I get a lot of documentation ideas during review meetings.

Conclusion

This was just a quick look into the complex relationship between development teams and technical writers. Many of the things may seem natural, but if you found something new, definitely give it a try. You might be pleasantly surprised with the results.

And remember, being a good technical writer is a continuous process. Like most others working in the IT field, writers need to keep on learning new things and building their knowledge. Try to push yourself and go into deeper and more complex scenarios beyond just the documentation aspects of your work.