How to work with your development team 

bri hillmer | October 5, 2016

Software developers have a reputation for being unapproachable. This isn't due to a common personality flaw. It is really just due to necessity. Nearly everyone in a SaaS organization needs something from the development team. Meanwhile, the team has their own goals and deadlines. 

This can make life difficult for a documentarian. After nearly 5 years' experience documenting at a SaaS organization I would like to share some tips for working with your development team.

Become A Resource

Get to know your customers. This is essential for your documentation. It also has the added benefit of making you a resource for the development team. 

I spent 2 months in support when I started at SurveyGizmo. I also spend at least 15 minutes a day in the support queue getting an idea about what customers are trying to accomplish and what questions they are asking. 

This allows me to serve as a resource for our development team. They often ask me for feedback with the expectation that I can anticipate potential customer pain points. If I'm not sure, I often act as a liaison between development and support. I regularly demo the features to support and gather feedback.

Go To All Meetings

Our Development team has a morning standup every morning at 9 am. I attend this meeting religiously. Even where there are documentation deadlines and other priorities that are more pressing. 

Attending meetings has several benefits.

1. You Know What The Team Is Working On

In an agile organization, priorities can turn on a dime. Often these changes originate as a shift or about face in development priorities. When you are part of the meeting where this is communicated you better understand where the change is coming from and what it means for other priorities. Because documentation priorities are directly affected by development priorities it is essential to understand these changes.

2. You Understand The Team's Challenges And Frustrations.

It can be easy to vilify the development team. The develop the software that support and documentation must support. Sometimes the software is confusing. Sometimes it has bugs. The frustration confusion and bugs cause can lead to an us-vs-them dynamic that is not at all constructive. 

The easiest way to combat this tendency is to engage with the development team. You'll find that the developers are far from villains. In contrast, their are often driven to carefully consider every aspect of what they develop. But, they are working under time constraints and are often called off their detail-oriented endeavors in favor of a new project. 

3. You Become Part Of The Team

Over time, you will be embraced as part of the team!

Make Yourself Available

As you become part of the team you'll need to make yourself available for new tasks. Your feedback will be requested. You'll be asked for copy for the application. You might be asked to help QA. 

These tasks are arguably not under the purview of documentation. But, reciprocity is a powerful thing. In return for helping with development tasks, developers will feel ownership for your responsibilities too. They will readily answer questions as you work through the documentation. They will fix things that are difficult or confusing to document. This results in better software and better documentation!

Get a Development Environment

If you don't have a development environment, you must get one. My development environment allows me to load up and interact with changes to the software before they are released. Having someone else do so is not enough. It is best to be able to do it on your own time. 

Get Good At Giving Feedback

Once you have a development environment you will be able to load features that are very early on in the development process. This is where things get hard. Giving feedback is an art. You need to figure how to give the right amount of feedback at the right time via the right avenue. 

1. Level of Detail

This is the most difficult part of giving feedback. In my mind, all feedback is fair game though super-detailed feedback is best given very late in the development of a feature. If you overwhelm the developer early on with a list of nit-picky feedback this can be frustrating for the developer. 

2. Timing

Timing is another key to giving feedback. Knowing when to give feedback requires judgement and a little trial and error. This is one of the main reasons that I love having a development environment. I can load a story and get a general sense for how much still needs to be done. This helps me to determine when the feature will need to be documented, but it also helps me to determine when to start giving feedback. You'll learn this with time. You can always ask if the developer is ready for feedback since all developers are different. 

3. Avenue

If you have access to the development teams' tracking system or Kanban board you can leave feedback items there. This is generally easiest for all involved. If not, you should also ask each developer how they like to receive feedback.

Conclusion

Working closely and collaboratively with your development team when documenting software results in both better documentation, as well as a better product.

[1] http://www.writethedocs.org/documentarians/

{{snippet.BriHillmer}}

{{snippet.Disqus}}