Search results

How do you stay updated with changes developers are silently making?

by Tom Johnson on Dec 20, 2015
categories: api-doc

You can stay updated with what developers are working on by analyzing the items assigned to the current sprint and asking the assigned developer for details.

A reader asks,

Our documentation team often gets blindsided by changes that developers make. We don’t feel like we’re kept in the loop with the updates and changes that developers are making to the application. How can we plug into the developer’s worfklow?

Developers rarely make changes that aren’t tracked in a system like JIRA. (JIRA is probably the most common issue tracking system, but your team may use something similar.) I’m betting they also follow an agile workflow.

My recommendation for plugging into the developer’s workflow would be to understand agile better by reading Jeff Sutherland’s book Scrum.

At the start of a sprint (usually a two-week period of work), the project manager identifiers all the work that developers will do during the sprint.

You should look through the items in the current sprint to see which are doc-related. Then follow up with the developers assigned to each item to get the details.

Developers rarely make changes outside of the issues noted in JIRA. If they do, call them out on this. If developers are making silent changes that aren’t noted somewhere in JIRA, let the project manager know and remind developers not to do this.

Most agile environments have standup meetings each morning where the developers are supposed to say what they worked on the previous day, what they’re currently working on, and any impediments. Theoretically, standups can be a place where you get updates about what’s going on in a project.

Unfortunately, many project teams misunderstand the purpose of standups, and the meetings become lengthy problem-solving/discussion/idea-exchange sessions for developers that drag on 30-40 minutes, wasting the time of technical writers with unnecessary developer detail.

I wish I had a better solution for standups. Attending standups for different project meetings can be a bear on my productivity. It’s good to show a presence on the team, but if the meetings aren’t helpful, then maybe just attend them every other day (switching among projects). Spend the time analyzing items in JIRA and meeting with individual developers instead.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.