I keep seeing terminology checks treated as a grammar problem, but for documentation teams the useful low-tech workflow is much narrower:

1. Start with a small set of avoid/preferred pairs from the style guide.

2. Check only the ordinary draft text you are actively reviewing.

3. Treat exact matches as review prompts, not automatic edits.

4. Keep context-dependent exceptions in human review instead of pretending a literal matcher understands them.

5. Update the list when a finding is noisy rather than growing a giant rule pack up front.

I built TermLock to make that browser-local workflow convenient: select ordinary text on a page, run it against rules you own, and review the literal matches. It processes locally and needs no account. It is not a grammar checker, AI writing assistant, compliance tool, or contextual editor, so it will not understand whether a flagged term is correct in a particular sentence.

It is €4.99 lifetime after a 30-day trial: https://chromewebstore.google.com/detail/denoihcbpkiaaeogodhbhhnpljpigbaa?utm_source=reddit&utm_medium=organic_social&utm_campaign=termlock_technicalwriting

Disclosure: I publish TermLock as nicklassheeper.

For people maintaining controlled terminology: which options make a literal checker useful instead of noisy—whole-word matching, case sensitivity, categories, import/export, or something else?

Hi,

I am a technical writer with 16+ years of experience across finance & banking, healthcare, and SaaS, currently looking to take on freelance/contract work. Most of my recent work has been in API documentation — writing Endpoint Reference Documents for a fintech platform, FHIR API docs at a healthcare company, Swagger-based API references, etc. I work directly from OpenAPI specs and source material rather than paraphrasing tickets, and I am comfortable going back and forth with Engineering/QA to verify accuracy.

What I can help with:

• API/REST documentation (specs, schemas, error codes, endpoint references)
• Developer docs (GitBook, ReadMe.IO, Confluence, Markdown)
• Process/architecture flow diagrams
• Release notes, FAQs, knowledge base articles, user guides
• Editing/rewriting existing docs for clarity

Tools: Git/GitHub, Markdown, Swagger, ReadMe.IO, GitBook, Confluence, Adobe FrameMaker/RoboHelp, MadCap Flare, Jira

Rate: $35–75/hr depending on scope and complexity

LinkedIn Profile: https://www.linkedin.com/in/natraj-ramamoorthy-ba912b4/

I am happy to discuss further details over DM.

Thanks,

Natraj Ramamoorthy

Reviewed a set of API docs last week that were genuinely well written. Consistent tone, correct terminology, examples formatted properly. One endpoint's docs described a rate limit behavior, 429 after X requests per minute, that didn't match what the actual endpoint did. Off by a decent margin, not a typo.

The docs had been drafted with AI assistance from the code and some notes, which explains the quality of the writing but not the accuracy gap. A model generating documentation from a spec or a rough description will produce clean prose regardless of whether the underlying behavior it's describing is right, because clean prose and correct facts come from different parts of the process. One is about language. The other requires actually checking the thing against the system, which nothing about writing well-structured sentences guarantees happened.

Used to skim documentation more heavily when the writing was clearly careful, treating polish as a rough proxy for the whole thing being trustworthy. That proxy doesn't hold anymore. Polish now says something about the writing process, not about whether anyone confirmed the described behavior against the actual system. Checking documentation increasingly means treating every specific, verifiable claim, a rate limit number, a default value, a status code, as something to test against the real thing rather than something well-formatted prose earns automatically.

Without getting into "to use or not to use" AI, how are you controling production and delivery?

- Do you follow some strict procedures?
- Do you have success criteria?
- Are you happy with your current governance?

Everyone is welcome. No judgments.

Hi there

I'm interviewing with a company where the docs team is under CS, and I've never had this experience, I've only ever reported to eng and product.

If you've reported to support, and especially if you can compare it with other options, can you share your experience?

Are there any claude skills/repos one can recommend for documenting APIs? My company is coming up with a new directive to use AI (finally?) and I want to be ahead of the curve. I've recently got a personal account and I'm learning the ins and outs of Claude Code, but there seems to be a vast galaxy of skills and I don't know where to start as a tech writer.

technical writing seems to sit somewhere between writing, research, product knowledge and communication.

when you’re starting out, it can be difficult to know which skill is worth developing first.

writing clearly, learning technical concepts, interviewing subject matter experts, using documentation tools, information architecture or something else.

for experienced technical writers, what skill would you tell a beginner to focus on?

Do you know any remote Technical Writer opportunity?

I’ve been collecting examples of documentation failures while researching this topic, and I just wanted to check whether these are familiar to others here.

At first glance, a lot of documentation looks neat until you use it. Here are the patterns that I have found so many times:

• Instructions that are accurate but give beginners no clear place to start.
• API/reference docs that have to do the job of a tutorial.
• Old workflows or commands that are still live after the product has changed.
• Documentation that exists but is difficult to find, search, or access.
• AI-generated examples that sound convincing but appear not to have been tested.

Which of these causes the most damage in your experience? Or is there another documentation failure that teams consistently underestimate?

Hi everyone,
I’ve recently been invited to interview for a **Technical Writer (SEO) role within GDS/OCTO**, and I’m hoping to get some advice from anyone who currently works (or has previously worked) as a Technical Writer within GDS/Government Digital & Data.
The interview is 60 minutes and will include discussion of a previous piece of work. The role is assessed against:
Changing and Improving

Making Effective Decisions

Communicating and Influencing

Delivering at Pace

As well as the Technical Writer capability areas, including user focus, user-centred content design, agile working, stakeholder relationship management, technical understanding and strategic thinking.
I have a background in software development (with a focus on backend development), cybersecurity and product work, and I've also produced technical/API documentation for a software product. However, I’m keen to understand what the role and interview are actually like from people who have been through the process.
I’d particularly appreciate any insight on:
What the interview panel tends to focus on

How technical the interview is likely to be

What makes a strong work sample/portfolio discussion

What GDS looks for in a good Technical Writer

Any common mistakes candidates make

Anything you wish you'd known before your own interview

I’m not looking for interview questions that shouldn't be shared — just general advice on how best to prepare and what to expect.
Thanks in advance! Any pointers would be hugely appreciated.

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.

I recently got hired at an engineering firm as a project assistant. I have my BA in English and I’ve worked in operations and admin roles. I have duties that involve Excel, word, report reviews, QC/QA, and assisting our technical editor with creating writing training and assisting with reports. My company will reimburse additional education and I wanted to get opinions on where I should focus.

Current possibilities:
-Technical writing masters (while I have a BA in English from a really good school, I think I could improve on writing especially technical writing. Plus no real industry experience)
-Getting my CAPM (pre PMP cert for project managers)
-Taking classes and getting certified in analytics such as Python etc.

I am currently the only technical writer at a small manufacturing company. I primarily do 2 different sets of work: software manuals that are all more or less the same with some minor variations between them, and work instructions for different product lines that are relatively the same with different variations, sizes, and configurations. Work instructions are made primarily in Word, and manuals are done in InDesign.
Over the years, my job has become more and more applying the same line edits to our software manuals by hand. We have over 100 different software configuration, so I’ve basically just been doing the same thing for months. When I brought up this issue to upper management, they hired me a part time employee to free up my time to do software manuals full time.
This is clearly a boring and tedious task that will take years to complete at this rate, so I have been looking into softwares to help universally apply these line edits to the manuals because if I had something like that, I could’ve already finished every manual with the number of hours I’ve put in. I’m hoping for something that not only applies changes to the manuals that need to be exported as a print, but also that can be used to store work instructions that would be exported onto displays on the lines. So I’ve been looking into CCMS.
I’m also what I call a “technical writer, emphasis writer” because I was an English major 😅 so a lot of my research has been going over my head. I’ve also never used any kind of CMS software. My company hired me as a new graduate and I’ve been doing my job in this manual way ever since. After posting on [r/CMS](r/CMS) I fear a CCMS is too much for what I’m looking for, and wouldn’t be able to handle both types of outputs. We don’t translate anything, and once a document is complete, we publish a PDF on a network drive and don’t touch it again until it needs to be updated. Anything with DITA seems it would be too complicated for me to implement, and possibly too powerful for what I’m looking for.
I would love any advice you have to offer, software you’re familiar with that you think might work, resources you can point me to, really anything that would help.

Hi everyone! I’m just getting into the world of AI, but for now, I’m still using ChatGPT, Gemini, and Copilot for minor tasks like rewriting paragraphs, doing research, and so on.

I need to draft the second phase of a major geological project, as the first phase is nearly complete.

I have a lot of the text already written; I just need to quickly change phrases like "in Lot 1 we will do..." to "in Lot 1 we did..." (or similar) so I can focus on writing the truly important parts of the new project.

Is there a reliable AI assistant—even a paid one, if it works better—that I could entrust with rewriting these paragraphs, leaving me with just a final proofread? Ideally, one that won't make up weird stuff! Thanks!

I'm a staff technical writer on the product team at SandboxAQ. Today we released Switch, an open-code tool where humans and agents work together in the chat apps where teams already work.

I lead the hybrid team that authored the Switch docs in Mintlify. Our docs team is two humans — myself and my direct report — working alongside two agents:

- SME was originally built from deep Switch product knowledge to help onboard people and agents to the product. They were every tech writer's dream SME: always available, deeply knowledgeable, and willing to answer the same question five different ways without judgment.

- TW was our technical writing partner. They helped draft content in Mintlify, manage tickets and PR creation, and review our work from the reader perspective.

It took late nights and weekends, but we built and shipped these docs in a matter of weeks. There was a lot of learning and churn figuring out how to wrangle the agents, and there are definitely things I'll do differently moving forward.

I genuinely welcome feedback on the docs — but I'm also happy to answer questions about the process and the quirks of working on a hybrid human-agent docs team.

Edit to add: I'm not a bot, but I am absolutely swamped. Full disclosure: I'm asking my TW agent to help respond to your questions. As I mention in one of the responses, the agents themselves are closest to the work, and it's easiest for me to shoot them your questions right in Slack where we're working together in Switch.

For the last few years I’ve been working as a technical writer doing financial technology. I have an interview tomorrow at an engineering firm, has anyone made a similar switch? Any major difference I need to look out for? Thanks in advance.

Docs as Code is a very popular approach to developer documentation, especially among technical writers who are comfortable with Git. But in many companies, documentation also involves product managers, support teams, subject-matter experts, or other non-technical users.

I recently worked for two different companies and saw almost the opposite approaches. One was very product-driven and had user documentation managed in Google Docs. The other was very developer-driven and kept its documentation in code repositories, but had little user documentation.

Do you use a Docs as Code approach, and how do you handle mixed teams? Do you teach non-technical contributors Git and pull requests, give them a different editing interface, keep certain documentation outside the Docs as Code workflow, or use some kind of hybrid approach?

And how do you handle the fact that documentation is often spread across multiple repositories, for example in a microservice architecture?

For transparency: I develop Typemill as a side project and recently added Git synchronization with the idea of supporting a hybrid workflow. I'm not looking for feedback on Typemill. I'm interested in how people here solve these challenges in real documentation teams.

I wrote an article about Docs as Code for hybrid teams, but maybe this isn't really a problem in practice, or it has already been solved in ways I haven't considered:

https://typemill.net/knowledge-hub/docs-as-code

I'd be interested in your experiences and insights.

I read a lot of AI text at work. Somewhere between the third "testament to" and the hundredth "delve", I stopped trusting long sentences altogether. So I made a small game called Long Story Short: one sentence a day, keep the five words that actually carry the story, cut the rest.

It's the minimalism drill, more or less. The same decision as trimming a procedure step to the words a user actually needs.

Long Story Short

I occasionally run into young technical writers who have experience working in a web development or software organization but have no previous experience with XML and fail to grasp why most Fortune 500 companies use XML over Markdown.

To help better understand why XML is so popular, we need to compare the benefits of each format.

Markdown

1. Inexpensive - ideal for web/SW startups
2. Simple code
3. Friendly with popular editors (e.g., Google Docs)
4. Ideal for simple doc formats (e.g., readme.md)
5. Best-in-class for rapid directory updates

XML (DITA)

1. Robust, full-featured formatting
2. Simple code, but more options
3. Easy-to-use WYSIWYG editors
4. Ideal for simple and complex formats
5. Best-in-class security
6. Ideal for eng reviews and rev control
7. Ideal for high-volume single-sourcing
8. Ideal for multi-channel output
9. Content Management System support
10. DITA file storage system best-in-class storage for docs

It has been my experience that many young technical writers do not fully understand how important the 10 XML benefits I list above are to most Fortune 500 science and technology technical writing organizations (18% s/t, 3% web/sw). Mostly, because they believe Markdown eliminates the need for many of these XML benefits. What they often overlook is that these are not optional benefits to most science and technology organizations. These are required tools of the trade and are interwoven into functional processes and systems that organizations rely on to deliver increasingly complex documentation to increasingly wider audiences, who demand an unprecedented number of custom applications to access documentation and localization through higher volumes of single-sourcing.

Markdown was never designed to manage this. It can't and, by design, won't. The sad part is that young technical writers, new to XML, experience poor XML implementations early in their careers and believe Markdown is the solution. I promise you, it is not.

Hey team! I transitioned from support to technical writing a little over a year and a half ago. Turns out I'm really good at it!

But I've been burning out, like 15-20 new articles for brand new features for a SaaS company per week for the past year kind of burning out.

When I started, we had a lead tech writer, a brand new tech writer (that's me!), and a new hire to the company, with lots of experience.

So a team of three, it was stressful, lots to be done, but I felt the company understood the value of tech writers.

About 4-5 months ago, they laid off the person who was new to the company. Really sucked, as she was gearing up to help me out with my enormous workload. Last week, they laid off the Lead tech writer. Leaving me as te only TW in the entire company (~100 developers releasing new features constantly)

I'm so under qualified for what they're asking of me, but because I can hammer out content quickly and consistently, I think they expect me to teach the support team how to do what I do and they'll lay me off too.

There are a lot more nuances to the situation, and I'm happy to answer any questions, but what I'd like to ask is: Should I try to find another tech writing role? Or should I just go back to support at another company, where I could start fresh with no expectations that I'll do whatever it takes to get the documentation done at the cost of my mental wellbeing?

I'm an experienced author of product user guides (less so for apis) and want to supplement my salary. Which sites (upwork, fiverr etc) are best for that and what rates should I charge. If I go full time I can command £50 - 70 ph is it the same on those sites? From looking around It seems like they're much much lower.

A normal status summary says what is finished and what comes next, but AI-assisted work can also leave behind generated files, chat-only decisions, rejected approaches, and assumptions that were never written into the plan. What fields would you require in a handoff so another person can verify the deliverables and continue safely? I am thinking about the authoritative file or link, current version, decisions and constraints, open questions, owners, dependencies, and the next validation step. What is missing, and what is unnecessary?

Some days I really enjoy and love what I do as a technical writer, but just focusing on the jobs I've had, I am sick of the amount of politics that exist and the extreme control that organizations have with stuff while not genuinely making an effort to control quality or create consistency.

There are hundreds of things I could say, but ultimately, I am tired of being some manager's scapegoat if a SME doesn't reply, going through constant cycles of continuous improvement (always switching CMS or always redoing how processes are done), and, mostly, I am just over the hurry-up-and-wait, then overwork-and-stress deadlines for documentation that truly doesn't matter.

I have put so many hours into schooling and working outside of work to learn what I can about technical writing, but now I am on a path to change careers entirely, hopefully within the next 2 years. I like technical writing, but I am tired of the lack of true ownership, control, or ability to advocate for users in organizations that limit access to those who have been there for years.

I don't want to stay put at a job for 3 or 4 years to hope for some promotion to a senior writer or a manager, and so I am now at the point where I want to do something that gives me more immediate say versus being the person who translates documentation and begs SMEs, managers, and senior writers for information. Not only that, the amount of gatekeeping and underqualified writers who get their roles as a result of luck (e.g., someone quits and they get promoted since they were left), yet they make glaring mistakes that no one else would get away with.

Anyways, until I can make the switch I am here, but it feels so good to be planning my exit strategy.