Happy Friday! Sometimes Past Phil is a legend. All too often, Past Phil is a bastard.
#techWriterLife
Experimenting with LLMs to generate release notes from requirements, email threads, support tickets, and QA reports.
Gemini helpfully "inferred" a config property. It was nice enough to highlight the hallucination in a second round of analysis, but still… so icky.
I'm wrapping up a project, strategic & self-paced. It's been rewarding, but the finish-line push is killing me. I need to submit it. I can take it only so far on my own. Still, it's so big that I'm always finding something to fix. Dang it, today is the day.
@mcc This skill is a facet of empathy, the ability to role play as a user, beginner or advanced. Empathy one of the superpowers of a good technical writer. If you include the tech writer earlier in development, you have a user advocate on the team & have a better chance of avoiding dev-focused solutions to user needs. And the doc can enhance the UX rather than act as a Band-Aid workaround for dev & design flaws.
@tezoatlipoca Whenever I get worked up & need to vent, I take it as a positive indication that I still give a crap.
Greatest strength: I love doing this tech-writing stuff.
Greatest burden: I love doing this tech-writing stuff.
@lclarke522 Lone writers of the world unite (separately)!
The best thing about being a lone writer: you get to do everything.
The worst thing about being a lone writer: you have to do everything.
What about tech writers, Mr. Stephenson? "All technical devices require documentation […], but this stuff can only be written by the techies who are doing the actual product development, and they absolutely hate it, always put the dox question off to the very last minute. Then they type up some material […], run it off on the laser printer, send the departmental secretary out for a cheap binder, and that's that." Snow Crash, ch. 48
I completed a major devportal migration. Yay!
Now I'm doing a lot of git housekeeping, merging and pruning branches. Ugh.
As a git noob, these big changes are all very stressful. Thank goodness I'm the only one working in the repo. Does it ever get any easier?
#git #gitHub #techWriterLife #technicalWriting #writeTheDocs #redocly
Video distribution in Google Workspace is painful.
Google Drive: Klunky file-system organization. Folks ask "Why not YouTube?"
YouTube: Permissions are annoying. Multiple folks need to access the account? You need an org YouTube account. The catch: org accounts can't publish org-private videos. Also, org-private videos don't support comments. Also also, YouTube floods your users with inappropriate ads and vids. Not very professional.
Overall, meh.
I'm migrating our devportal in Redocly Realm (highly recommended). Ran the preview server & something didn't look right. The prompt was just "Press (q) to quit". Started to worry then realized it's missing total error counts & "or (e) for full error log". The migration has been smooth, but it's taken a while because I'm doing all the refactoring, coding, writing, and styling. I've never seen a run with no errors before.
Yay!
Adobe: You're using an old version of Photoshop! Upgrade for the latest functionality!
Me: No thanks. I still have trauma from when I upgraded & Photoshop refused to run unless I upgraded my display card & didn't allow me to revert. Kinda messed up my workflow for a while there. Plus: "new functionality" = "AI horsefluff that will likely turn my laptop into a space heater".
It me. I'm Phoebe and Joey.
#documentation #techWriterLife #technicalWriting #writeTheDocs
Documentation win: support ticket from a customer who developed to our docs & is getting errors. Everyone's first impulse (including mine) is "gotta fix the docs!" After investigation, the docs are good & a code fix resolves things. Customer is mollified & the tech writer (me) is pretty damned chuffed.
@ddoomen If they're lucky, devs get to work with technical writers who LOVE writing #documentation. Devs can then do more of what they love while the doc enables users, accelerates adoption, and lightens the support load.
Execs are not your friends, but having an executive ally for docs is good for my mental & emotional health.
Pulled into a day-in-the-life test. Cross-functional, multi-timezone team on the call. Kind of fun until a dev reports a Big Bad. Shares his screen. Tensions rise. I see something that explains the behavior. Is it that simple? I ask "is your app configured for X?" After a beat everyone chuckles as the tension evaporates. "Wow, Phil. Thanks! Good catch!" As a tech writer, I'm usually a Breaker of Things. Feels good to be on the other side for a change.
They're going to kill a service I've worked on for decades.
I'm ecstatic.
1. The doc, like the service, is a hulking monster & deserves to die. It has grown organically, bloated & mutated like a blue whale run through the filter of "The Thing" & "Annihilation" films.
2. Coworkers building the replacement thank me for comprehensive doc on components, workflows, the domain, & a record of the service's devolution/mutation.
Feels like a rare second chance.
I have experience with auto transcription services. They're OK, but their quality is sketchy, like bottom-tier facial recognition with lots of weird mistakes in transcription & topic organization. I spend nearly as much time debugging their output as I do building a timestamp list manually (skipping through at 2x speed).
I lead a release meeting every 2 weeks, a survey of new features & fixes for all services & apps plus a preview of high-profile items. I distribute the recording for folks who can't attend with a list of timestamp topic links I build.
Feedback has been overwhelming, with "genius" applied to the links.
It's less "genius", more "empathy". Who can sift through 20+ minutes of meeting? What's the point of all the effort if it's unusable?
Client Info
Server: https://mastodon.social
Version: 2025.04
Repository: https://github.com/cyevgeniy/lmst