r/technicalwriting • • 11h ago

How do you keep your how-to docs and SOPs from going stale?

0 Upvotes

Where do your processes live (a wiki, Confluence, Google Docs, videos)? Who's responsible for them, and what happens when the software changes and half the screenshots are suddenly stale or plain wrong? Does somebody fix them, or does everyone just ask in Teams or Slack when they're stuck or find something that's clearly outdated.

I'm building something, or rather have built something in this space so I'm quite biased and going solely from my own experience or past struggles, but I'd rather hear how it actually goes for you folks than guess. Or I suppose I'd want to know what your pain points are and what would make this process easier for you.


r/technicalwriting • • 1d ago

Is "80% of the way to ASD-STE100" a useful target for cleaning up AI-written docs?

0 Upvotes

Andrej Karpathy suggested asking LLMs to write "80% of the way to ASD-STE100" to get clearer output. I wanted to see how far that idea goes, so I built a small open-source skill for AI coding tools (Claude Code, Codex, Cursor) that rewrites text in two passes:

  1. Remove common AI tells (based on Wikipedia's "Signs of AI writing")

  2. Rewrite in an STE-inspired style: short sentences, one idea per sentence, active voice, no filler

It does **not** enforce the full STE dictionary or the approved-word list. That's the "80%" part.

**Before:** "Great question! Kubernetes liveness probes are a powerful mechanism that enables the kubelet to determine whether a container is healthy — and it's not just a health check, it's your first line of defense…"

**After:** "A liveness probe tells the kubelet if a container is healthy. If the probe fails, the kubelet restarts the container."

My questions for people who actually work with STE or controlled language:

- Which STE rules matter most for readability outside aerospace?

- Which rules would you drop for software docs?

- Is "partial STE" useful, or does it miss the point?

Repo (MIT) if you want to look at the rules I used: [Dodaios/ste80-humanizer](https://github.com/Dodaios/ste80-humanizer)


r/technicalwriting • • 2d ago

CAREER ADVICE Can I do technical editing outside of my industry niche?

2 Upvotes

A friend of mine offered to refer me to a technical editor job at their place of work. The job is in finance and requires I apply GAAP (generally accepted accounting principles), as well as AP style.

I’m confident I could pick up AP quickly as I’ve used it before, but worried about GAAP. My background is in health as a DTC/B2B copywriter (senior/manager level) and this would be my first “editor” title.

If I were to get this job, would I suck at it? Do technical editors ever get hired without industry-specific expertise? Is it ok that I wouldn’t be able to apply GAAP on day 1, & would need to learn on the job?

My last job was a hostile work environment that ended in a lawsuit (I won), so even if I’m able to get this job, I’m hesitant about potentially re-entering another shitty situation.


r/technicalwriting • • 4d ago

QUESTION Technical Writing meetups in SF next week

11 Upvotes

Does anyone know of any meetups or technical writing events in SF next week?

I have never been to San Francisco before, and I am planning my first trip next week.

I am planning to go there on vacation after months of job hunting (220+ applications) and also check out the WtD meetup.

But are there any other technical writing (or adjacent events) I could go to meet fellow technical writers?


r/technicalwriting • • 4d ago

POLL Just for fun, let’s do a poll!

3 Upvotes

Are you an experienced technical writer that’s currently employed?

Or are you currently unable to leverage that experience into an employment situation?

Let’s see how everyone is doing in this lovely job market!

193 votes, 2d left
Gainfully Employed 🙂
Painfully Unemployed ☹️

r/technicalwriting • • 5d ago

QUESTION Technical writing beyond software

52 Upvotes

How many members of this sub work on something other than software?

ETA- Most of my experience has been in tools, fasteners, and pumps.

ETA- Writing manuals was my favorite part of my last job.

Edit 11/13: I appreciate the responses. It's interesting to learn about all the different kinds of technical writing one can do.


r/technicalwriting • • 5d ago

QUESTION Images with callouts

3 Upvotes

I want to pick your brains about images / screenshots.

Do you use them? Do you use callouts such as circled sections, numbers, and lines? What programs do you use to create them? Do you maintain source files or do you make new ones every time? How do you handle consistency such as making sure that all your lines have the same line weight and numbers / letters use the same size font? Do you have any other issues or solutions for improving workflow for maintaining these things? If you could design a tool to improve your experiences with images, what would it do?


r/technicalwriting • • 6d ago

Holy Heck is Paligo's Nexus Bad

11 Upvotes

So, my manager has decided to explore Paligo's Nexus tool. And as bad as their UI and workflow are for normal publication flows, this thing has managed to accomplish something I would have thought impossible: it's somehow worse.

The first problem is their theme tool. It's supposed to be a VS Code plugin that claims "For an edit loop without uploading, the Paligo Theme Studio extension for VS Code renders a theme folder against a real publication as you save." Except that description bears almost no resemblance to what it actually does.

Paligo hands you a folder full of Twig, CSS, and JS, then tells you it’s a “theme” as if you’re building a normal front-end app. In reality, you’re packaging a server-rendered publication template, uploading it to their platform, and then waiting for their backend to reassemble the whole docs site with your design bolted on. It’s not “live preview” in any meaningful sense. It's a long, fragile chain of packaging, uploading, and rendering. That's not a theme. It’s a hostage note to a render pipeline.

And the “customization” isn't a theme layer either. It's a late-stage JS patch job: the page is rendered by the platform, then the client-side script injects the branded content, images, and structure at runtime. The “customized” experience is not actually the template: it's an assembly that occurs in the browser after the fact. What's really happening is that they're shoveling brand assets, nav chrome, and layout bits in via JavaScript when a page loads. Their marketing text is an overly elegant way to describe a system that is, under the hood, rendering a shell and then layering the “real” design on top with script, like too much makeup trying to cover the ugly underneath.

Each render takes over three minutes (yes, I timed it) so if you want to tweak an element and see what changed, that's a three-minute wait... each time. Color not quite right? Three minutes before you can see if your change worked. Font size a little too small? Three minutes before it renders with new headings. Logo cropped funny? Three minutes before you can see if your edit fixed it. Every time, the platform has to repackage the bundle, upload it, validate it, and re-render the publication on the server before you can even see whether a change did anything useful. That is not “live editing.” My smallish sample taking three minutes is a reminder that what's really happening with every edit is a server-side deployment with a side of disappointment.


r/technicalwriting • • 7d ago

How do you decide what belongs in release notes: bug fix, refactor, or internal change?

11 Upvotes

I was editing release notes from a rough development log and hit a familiar boundary: when does an internal engineering change deserve user-facing space?

Here is the source material:

  • Refactored the export worker.

  • Fixed filtered CSV exports dropping rows.

  • Added a retry button for failed exports.

  • Export history now shows file creation time.

  • Larger exports are still slow. No benchmark yet.

  • Scheduled exports were discussed, but not implemented.

I kept the missing-rows fix, retry action, timestamp, and the current limitation. I cut the refactor and avoided saying exports are faster. The draft also says scheduled exports are not included rather than vaguely teasing them.

My current criteria are:

  1. Can the user now do, avoid, or correct something?

  2. Does the change affect observable behavior, support expectations, or existing work?

  3. Is there enough evidence to describe the scope accurately?

The difficult case is the bug fix. If users may have relied on exports with missing rows, the note may need affected versions and guidance on whether to re-export old files. The development log did not contain that information, so I would not invent it in the announcement.

How do you make these calls? Do you include refactors only when they change performance or reliability? How do you handle corrected bugs that might require users to revisit earlier work?

Transparency: I moderate a small community, r/NotesToOutput, where I posted the longer worked example, but the question and example are complete here. https://www.reddit.com/r/NotesToOutput/comments/1xqz5wp/the_bug_fix_belongs_in_your_release_notes_the/


r/technicalwriting • • 8d ago

Dear vendors

26 Upvotes

I can say that the way you act in this sub has turned me off of at least 3-4 of you. I don't think we need some kind of moderation, but you guys really need to think more carefully about engaging here. With love, someone who has considered vendors in the past and will consider vendors again.


r/technicalwriting • • 7d ago

College Undergrad Looking to Freelance

0 Upvotes

So I'm an undergrad in Electronics and Communication Engineering. I am a beginner at most things. I've only got C fundamentals for now and I'm trying to learn Linux and further get into robotics. But I have some writing experience(nothing professional and nothing specifically tech-related). I wanna pursue freelance tech writing as an immediate professional goal but I have no idea what to do for now. Where should I even look for it? How to build a profile, proof of work? And how to get monetised?

P. S. I'm open to online, remote work, preferably from established dev platforms.


r/technicalwriting • • 8d ago

SEEKING SUPPORT OR ADVICE Where to look?

1 Upvotes

I am in need of someone to help me document personal messages for court evidence. The conversation is between two parties newly co-parenting. This is a complex matter with sensitive family topics. The goal is to spotlight certain patterns of behavior. Does anybody know where to find this type of writer or documenter?


r/technicalwriting • • 9d ago

Doc as Code, I'm getting replaced. Advice?

36 Upvotes

Just found out that my company has tied AI into the source code of our software suite and no longer need a technical writer to write user guided documentation. The docs are soo accurate, they can copy and paste to the knowledge base and even automate dev work and SME reviews into the solution...

Anyone encounter this? Is there a future left in this industry? Are people adapting? How can I seque my skills for the next role, if there is one..

Any comments would be much appreciated, thanks guys -


r/technicalwriting • • 9d ago

How to transition to aerospace/defense tech writing?

6 Upvotes

Hi all. During the month of October, I've had 3 interviews with 3 different aerospace/defense companies. One of them was a Junior tech writer role. So me having 4 years of tech writing experience thought this wouldn't be too hard.

However, I came to find out that I would always be beaten by someone who has experience writing for DoD. Even in the junior role. How can I leverage myself to land a position if I don't have experience in DoD? Courses? Reviewing MIL-STD docs? Any advice helps.

I would also like to know how you stepped into the industry without prior DoD experience.

Thank you, writers! :)


r/technicalwriting • • 9d ago

My first reader asked what 'use the power button' meant

3 Upvotes

I had just started practising technical writing and tried rewriting one task from a battery manual. We'd downloaded the Jackery manual while looking at storage for our flat, so I used that. My task was to explain how to turn off the display while leaving the unit running. I gave my partner just my draft and asked her to mark anything that needed an explanation.

She stopped at the sentence 'Use the POWER button to turn off the display' and asked whether that meant a tap or a hold. I'd treated the task heading as enough context and shortened the action to a button name. Reading it back after her question, I had no press duration or starting condition in the draft.

We went back to the button-control table. I read the English rows and she checked the corresponding Dutch ones. A single press with the unit already on controlled the display; a hold of more than three seconds controlled system power. Those two operations were distinguished in both language versions.

I rewrote the step as 'With the unit running and the display lit, press POWER once to turn the display off' and gave her the revised draft. This time she described a single press with the display already lit when I asked her to explain the step back. I saved both drafts with her question beside the original sentence.


r/technicalwriting • • 9d ago

Technical Writing Research

0 Upvotes

Hey writers. I'm working on an AI research engine that pulls empirical claims, stats, and production bottlenecks, etc from 80+ primary sources with citations. The end goal would be to save hours of time on research and speed up the drafting process. What would take a tool like this from "that's pretty cool" to "I'd pay for this yesterday?"


r/technicalwriting • • 10d ago

HUMOUR Technical Writing Roles That Pay INR15K/ INR 20K Something Are Outrageous

0 Upvotes

Stop treating technical writers as content writers.


r/technicalwriting • • 10d ago

MCS Recommendations?

4 Upvotes

I'm looking for recommendations for software to build a modular content system. Basically envisioning a string of choices starting with a user's role that will then pull and serve discrete chunks of documentation as a single process flow.

I know this is still sort of a new thing, and the de rigueur is to just build your own with PHP or Python or something and feed it DITA XML files, but if there are decent off-the-shelf solutions I'd definitely want to check them out.

I know Madcap has their own MCS product now, but we're a Flare company at the moment and my experiences with them as a vendor have been increasingly disappointing over the last couple years.

Any help is appreciated!


r/technicalwriting • • 10d ago

Recruiter and HR rep not familiar with candidate and samples?

0 Upvotes

Here's a situation that seems odd. I'm currently an employed technical writer, but curious if anyone else has experienced something similar.

Recently, a recruiter contacted me about another tech writing opportunity. I'm not really looking for anything new but have an operating principle that it never hurts to have a conversation. So, I sent this person a link to my portfolio website, which contains writing samples from projects I've worked on and my resume. A few days later, I have a call with this recruiter and now the odd part: this person seemed unfamiliar with my work experience and writing. They also didn't seem to know much about the job they were repping. Ok, whatever. It's a top of the funnel first contact.

Fast forward about a week. Now there's a second interview with the HR rep from the company + someone else from that org, probably engineering. We're moving further into the recruit, hire funnel. Now the odd part: the HR person had their webcam positioned so it cut off the lower half of their face. All I could see of them was from their nose up, throughout the entire interview. And, like the recruiter, this person didn't seem aware of my experience and writing work.

Both of these conditions raised some warning flags with me. Like I noted above, I already have a decent job, but these 2 experiences were just off. You'd think someone would at least take the time to be passingly familiar with a portfolio if you sent a link. I'm letting this one drift off onto the ice floe. Have other, more active job-seekers had experiences like this?

TL;DR: 2 rounds of interviews, no one seemed familiar with my background and writing samples that were provided (LinkedIn profile, GitHub profile, separate online portfolio and website). Anyone else go through something similar?


r/technicalwriting • • 11d ago

SolidWorks Drawings in Documentation

6 Upvotes

Context:

I started a new job at a small manufacturing company (50-100 ppl) recently and my main responsibilities will be writing new SOPs, updating/creating the user manuals for our products, and anything else that is documentation related.

The company is very far behind documentation-wise, and I do not have any technical writing experience beyond having majored in English in college.

I started rewriting some parts of an existing manual, and I've created a couple of SOPs/SOP templates so far, but I've done all of this in Word. I'm used to Word and honestly fine with the typical annoyances that come with it, but I'm finally running into issues trying to incorporate engineering drawings from SolidWorks into my documents.

Issues & what I've tried:

- The first few SolidWorks drawings I messed with were on PDF, so I just opened them in Inkscape and saved them as an SVG, and it worked relatively well. I liked that I could alter the drawing/remove writing that wasn't needed to fit the context of the document, and it didn't look that bad.

Our engineer recently sent me some more shaded drawings (exported them as PDFs), but the shading was rendering tiny horizontal lines in Inkscape.

- I tried to take the PDF and add it as an object in Word, but that looks horrible too.

- Engineer sent me a PNG early on, but it was extremely blurry and small. I later saw online to get the PNG as a screen capture with a high DPI, so I doubt he had done that.

I think I tried a couple more things, but this is the gist. I liked the editability of opening the drawings in Inkscape so I don't have to ask our engineer to make tiny edits here and there (for example, he added text/lines to the drawing and I might like to split the drawing into two, with half the text in one image and the other half of the text on the other).

I've looked through a bunch of SolidWorks forums and that's where I found some of the above solutions, but I'm looking for any advice you may have for me.

Is it time to give up Word and move over to Adobe? Which Adobe products would cover everything I need/want? Is there a different way to export shaded drawings that work better? Should I give up messing with Inkscape and just ask the engineer for a bunch of edits?

Thank you in advance for any help or advice you can give me! I know I'm all over the place in this post, just looking for some direction before I keep asking for edits on the drawings or before I ask the big boss for a subscription to something.


r/technicalwriting • • 11d ago

QUESTION Any signs of hope or course correction lately?

28 Upvotes

I don’t need to go in detail about how bleak this career has felt over the last few years. Does anyone have any positive stories or feelings about where things are headed in terms of layoff patterns, AI, and the many factors affecting/changing this field?

I’ve seen glimmers of hope in the tech industry that AI usage was being reversed or failing to meet expectations, people getting rehired, etc., but I haven’t heard how much this has applied to tech writers lately.


r/technicalwriting • • 12d ago

SEEKING SUPPORT OR ADVICE Where are the jobs?

56 Upvotes

I have been out of work since April. I'm finding absolutely no traction despite a broad portfolio (mostly software, but a little bit of telecom and civil engineering) and ten years of experience, including managing an entire documentation department.

I am in a tailspin. AI screeners eliminate me after six hours of "careful consideration." The rare interview ends in ghosting. Some nonsense called "AuraOne Human Data" is choking out all the legitimate job postings on Indeed as of late. I don't know where to turn.

Where are you finding work? And I don't mean only in terms of what sites you're using to look for openings. Like, where are the physical locations where I can trade my time for money? Where can I find the slightest glimmer of hope that I'll have an income again?

Any suggestions appreciated. Thank you in advance.


r/technicalwriting • • 11d ago

What does your org use for internal documentation?

2 Upvotes

I manage our end user documentation with Madcap Flare. Previously we had a public/private site using wiki.js for more technical information. We recently migrated most of the public portion of that site to our Flare project and for whatever reason management shut down the wiki site.

We've got some people looking for a place to put internal content for development and support. My previous employer used Confluence, but I think that's too expensive a solution for our purposes. If I put it in Flare, we'd be limited in who could contribute and I'm resource-constrained as it is, so I'd rather not add to my personal workload. Ideally whatever we use would be accessible to our enterprise AI tools. I honestly don't have a wide experience in this area. Any suggestions that we could look into would be appreciated!


r/technicalwriting • • 12d ago

Writers told me their screenshot automation already works. So where does it still break?

Thumbnail reddit.com
0 Upvotes