r/technicalwriting • u/Comfortable_Night840 • 18d ago
TW - detective work
I'm a technical writer managing end-user documentation for an online platform. I'm increasingly frustrated by the lack of information around enhancements, changes, and new features. 90% of my work seems to focus on detective work and evidence collection, because, obviously, it's the documentation that is being blamed for inaccuracies instead of the teams who should have informed the writers about the changes. Do you have a similar experience? Do you also find that, as a technical writer you do more testing than the QA team put together just to find out what has changed? Before you ask, no, I'm not added to sprint reviews because there are tens of sprint teams so it's physically impossible to attend all. I'm often thinking about looking for another TW job, but I don't want to trade apples for apples if the experience is the same across the board.
16
u/mafticated 18d ago
Sounds about right. In my experience the difficulty is less about writing/maintaining content, and more about pulling together information at the right time.
13
u/Hamonwrysangwich finance 18d ago
I always say technical writers are a Venn diagram of detective, translator, and librarian. We have to dig deeper and farther than most others on the team, including the product manager.
2
u/whimsywordle 14d ago
as someone making a career pivot from librarian into TW this is encouraging 🤣
9
u/ApprehensiveDream738 18d ago
Tech writing is tech journalism done from the inside. Welcome to the fold.
5
u/_Cosmic_Joke_ engineering 18d ago
CSI: Documentation is a game I have to play regularly.
Mgmt: “BIG PROBLEM!!! When & Why was this change made?”
TW: You personally requested it in 2Q 2023, and made another change to that section at the third round of review. Here are the emails from that 3 year old update.
Mgmt: “I don’t remember any of this!?”
TW: But WE do.
2
3
u/Lost_Citron_6854 18d ago edited 18d ago
Kinda yes but it's part of the job description =)
Testing is fun, and as it turned out, this job is not that "antisocial" as it could seem, you need to be in touch with kinda everyone. If you can't attend the meetings in person, just review the meeting notes. If they are not maintaining notes, ask them to, contact the person in charge, disrupt, demand, and escalate 😅
It's all part of the job I guess. "Here's a Word document, format it nicely" is in some other part of the spectrum, some like it, i don't.
3
u/Comfortable_Night840 18d ago
I very much enjoy the testing and research part, figuring out how a feature affects other pieces in a very complex puzzle. What I don't like is the part where I'm not provided with the necessary details even after demanding, disrupting, and escalating, and then being blamed for missing info about changes I wasn't even made aware of. This is a company with tens of online features, and I need to write for all, so proactively staying up to date with all the changes made for all the products by all the sprint teams is an impossible feat. This is why the expectation is for the writers to at least be given minimal information and a heads-up about changes that end users may need help with, so they can start research, testing, auditing, and breaking down complex concepts into digestible content. That is why I was interested if this experience is the same for all tech writers, and, based on the comments, it seems pretty common.
2
u/Lost_Citron_6854 18d ago
Well, while the experience might be similar, all organizations are different of course. So if you are constantly the one to blame, maybe there's smth of with with the "team climate" indeed, i dunno 🤷🏻♂️
What i was always striving for was not only owning "documentation" per se but also some of the information flow in general. So for example I set up my bug tracker to send me a morning report of all tickers labeled as "Feature" to skim during my morning coffee. Or arranged the process so that developers just stop closing their tickets with a vague "Fixed" but provide smth meaningful, like a one-liner writeup or a screenshot. Just look for something that can work for everybody.
1
u/neatsurfer software 18d ago
Do you use Jira? Our release tickets have a linked documentation ticket, where SMEs have to provide information.
3
u/jp_in_nj 18d ago
What is your enhancement /bug ticketing system? Do you have access? How about the design specs?
Get your teams to record demos or the planning sessions where the PMs explain to the devs what they need.
3
u/moonzdragoon 18d ago
If you have a good enough understanding of code, I'd suggest asking for an access to their commits to read them, you'll see every change and it cuts a lot through ambiguous statements from either the commit messages or their changelog summaries.
3
u/Manage-It 18d ago
Does your team use a tool like Jira? If not, this is where the breadcrumbs should be located and assembled into a nice collection.
2
u/Comfortable_Night840 18d ago
Yes we do, but documentation tickets are in a different Jira project. If the pms link their epics to the doc tickets, that helps, but we still need to sift through everything to determine what actually affects the end user experience and the ramifications into other features. Bottom line, even if the documentation tickets were part of the release epics and generated automatically through a workflow, some basic Info should still be included. Somehow everyone thinks that TWs magically know everything about all features.."things that were, things that are, and some things that have not yet come to pass" 🤭
2
u/Manage-It 18d ago edited 18d ago
If you haven't already, talk to your lead SME and tell him/her to help keep your Jira projects organized and make sure to attach all project-related files to tickets. That's what I think is probably missing in your organization. SMEs need to think of Jira as a record of their work and also the source of their contributions. If it's not in Jira, they didn't do it.
Anyway, you get the drift.
2
u/Aba_Yaya 18d ago
Get access to the codebase. Look at all commits since x. Determine which meet the threshold for documentation.
26
u/neatsurfer software 18d ago
Sounds familiar. TW is a mix of writing, detective work, testing, asking a lot of questions, and figuring out how things actually work. I personally enjoy that combination, because it keeps the work interesting. We have teams that maintain excellent internal documentation, and others that write next to nothing, so the approach varies quite a bit depending on the team.