Staying updated about what developers are changing -- my techniques for information sleuthing
Docs are rarely on the forefront of developers’ minds, and as a technical writer, at some point you’ll realize that important details were never communicated to you. You might only find this out when someone does a bug bash on some user flows and complains that the docs are out of date, or when others outside the development team contact you to tell you that something is “incorrect.” Then you realize that somewhere, some developer made a change to something, QA tested it, and the team pushed it out to production — all without informing the technical writer to update the documentation. Nothing makes tech writers feel so marginalized and excluded as when this happens.
The most commonly asked for solution (by technical writers) is for others to keep them updated. Sometimes writers include a checkbox on JIRA items that indicates some doc update is needed. Or maybe by attending daily standups and other meetings, you hope to get ahead of the curve. If your process is working for you, great. If like me you still find yourself occasionally left out of the loop, rather than feeling indignant and overlooked, there is another approach: information sleuthing.
The general idea of information sleuthing is to embrace the pull rather than push method for information. Don’t get upset when engineers fail to push information to you. Be grateful when they do, but don’t expect it. Instead, pull the information from various sources, piecing together the changes. It’s not hard to do this, given that engineering teams spend all day online and hence leave a visible footprint, but it does take some time. You can spend about 30 minutes a day just sleuthing for information.
Why am I using the word “sleuthing” here? Admittedly, it’s a more playful and interesting term than simply “gathering.” However, it also connotes a sense of playing detective. When you’re looking for information, you’re not just looking at any type of change but rather changes that affect documentation (and which weren’t previously called out to you).
Here are some sources that I consult when I’m in information-sleuthing mode. The sources will vary based on the tools your engineers use.
- Quip’s recent updates
- Chime chatroom
- JIRA for the sprint (sprint items)
- JIRA for the project as a whole (all updates, including the backlog)
- Launch readiness wiki
- All wiki updates
- Commit logs in repos
- Code Review requests
- Weekly update emails
- Mailing lists
- QA test scripts
- Feature roadmap and planning documents
Of course, daily standups and other meetings can provide a source of information too, but these sources tend to burn up your time with more noise than signal.
I find that when I regularly browse these information sources looking for relevant updates, I can better stay ahead of releases and anticipate changes. I also find it somewhat relaxing and fun to browse these sources. It’s not mentally taxing to glance through commit logs or JIRA updates, for example.
When I do identify some important information, I’ll often reach out to the person on Chime or email to get more information or to put myself on their radar.
Again, information sleuthing probably shouldn’t be required in a “doc-first” type of company. But despite an engineering team’s best intentions, they are often focused on code and deployment more than docs. Docs slip past their attention. But there is almost always an online footprint into changes that engineers are making, and if you follow it you can stay ahead of the game.
Just for fun, I’m including a few survey questions to gather your feedback and experience. You can see the ongoing results here.
About 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.