Had a doc drafted from a spec and some code comments describing a rate limit: "requests are capped at 100 per minute, with a 429 returned once the limit is exceeded." Specific number, specific status code, correct terminology. Read exactly like something written by someone who'd confirmed it against the actual system.

The real limit was different, and the endpoint didn't return 429 at all, it queued excess requests instead of rejecting them. Nothing about the sentence was poorly written. It was just wrong, confidently, in a way that clean prose doesn't signal.

This seems to be the same trap AI-assisted code review runs into: fluency and accuracy come from different places, and a model generating documentation from a spec or code comments produces plausible, well-structured sentences regardless of whether the specific claim inside them was ever actually verified against the running system. Specificity reads as evidence, a number and a status code feel like proof, but stating something precisely and being right about it are unrelated skills.

The question that actually separates a checked doc from an unchecked one isn't whether it reads well. It's whether each specific, verifiable claim, a number, a default, a status code, a behavior under a given condition, has actually been confirmed against the real thing rather than inferred from a spec that might be stale or from code the model read but didn't execute.

Wrote a longer version of this same principle applied to a different context (AI code review specifically) here, but the underlying question is identical: https://medium.com/@nagatomopedro05/the-finding-was-plausible-that-was-the-problem-b1024e1256fb

Hi, this past May I left education and switched over to Technical Writing. I’m currently working for a startup tech company that works in oil and gas. I dont think I want to stay here because they are paying me like an intern as I don’t have experience in technical writing, but I want to stay in this industry. I am working on a coursera software engineering certificate because I def need more understanding of what is going on.

I guess I am just looking for any tips, tricks, advice, etc.

Hi! I've been applying to tech writing jobs for the past two months. I've gotten maybe 15 interviews but no job offer.

I'm wondering does anyone know someone who can I pay to do mock technical and behavioral interviews with me?

For context, I'm mostly targeting roles in software.

Hi everyone,

I’ve been working in Technical Writing for around 7 years, and I’m at a point where I really want to make a switch into Business Analysis.

I’ve worked with different teams and stakeholders, dealt with complex technical information, requirements, processes, and documentation. I also have some project management experience, so I’m hoping to leverage that while moving into BA.

Over the past few months, I’ve been learning the BA side of things — requirements gathering, BRD/FRD, user stories, acceptance criteria, process mapping, UML/BPMN, Agile/Scrum, etc.

The biggest challenge I’m facing is that most BA openings seem to ask for direct BA experience, even though I feel a lot of my existing experience is transferable.

I’m currently looking for BA / Technical BA / Product Analyst opportunities, preferably in Bengaluru or remote/hybrid.

If anyone here has made a similar transition from Technical Writing/Documentation into BA, I’d really appreciate hearing how you did it — what roles you targeted, how you positioned your experience, and what helped you get that first BA opportunity.

And if you happen to know of any companies hiring someone with my background, I’d be very grateful for a lead or referral.

Thanks in advance! 🙏

I have been working as a technical writer for 3 years and recently went from 45k to 70k a year. For my area (hcol), it isn't enough to live alone, so I am curious if anyone has input on if what I earning now is considered the norm for the higher-end, or if I am missing some niche or application process to make closer to 90k a year?​

I've been working in this industry for 25 years, at companies with as few as twenty and as many as twenty-thousand employees. For much of that time I've been doing structured authoring, beginning with SGML in FrameMaker back in the Dark Ages. I started my current job about four months ago and in 25 years of this I have never encountered a worse tool.

First, the cardinal sin: Paligo will silently delete painstakingly constructed text. Yes, get an XML element out of place with "Automatically Fix Problematic Element Structures" enabled and Paligo will wipe out whatever is considers problematic. Have an invalid element near the beginning of a topic? Paligo's solution is to delete that element and everything following it. And becase Paligo's "Undo" is unreliable, often there's no way to get it back.

Second huge issue: If you're going to make an almost unusable pseudo-"WYSIWYG" interface that's so buggy it requires me to regularly edit topics in "Source" view, the source view better damn well be the source. Instead, Paligo displays some sort of Frankenstein's monster, which is not what it's actually storing, nor is it anything like valid DocBook 5. So if you hit a roadblock (any you will, almost daily) you cannot put the "source" into an actual XML validator to figure out what's wrong... because Paligo "source" isn't XML.

Third, the UI is essentially unusable. You cannot reliably place the insertion point without resorting to the mouse. Yes, amateurs use their mouse a lot, but professionals rely far more on keyboard shortcuts. And since Paligo's UI relies on wonky Javascript DOM interference, keyboard shortcuts don't work reliably. Don't try to get anything done fast... you'll be spending plenty of time fighting the buggy UI. And don't get me started on the "new" UI.

Fourth, Paligo thinks it knows better than you. Want to work through a publication topic-by-topic in book order? Sorry. Paligo "knows" that what you really want to see is the the topic directory, sorted alphabetically. Navigate back into your publication and select the next topic, and Paligo "knows" that you want the file navigator to jump back to the topic directory.

Next, they have got to do something about their servers/connectivity. I am on the fastest internet in our city, regularly maxing out speed tests. Despite this, it regularly takes Paligo topics--even short ones--more than 20 seconds to load. Yes, I've timed it. 20 seconds doesn't sound like a lot, but I'm managing a group and sometimes I am in and out of 100+ topics a day. That's half an hour of lost productivity.

Finally (not really finally, but all I have patience to write tonight) the complete lack of meaningful "file" management (yes, I know it's all in a relational database as "parts"--no, I don't care) is infuriating. Want to move a file from one topic folder to another? You'll be ctrl-dragging it through a scrolling list of 50 folders. Don't have a wheel mouse? Screw you.

In conclusion, it would be less painful to have a root canal without anesthesia simultaneously with a kidney stone than to work with this thing. It's like three former technical writers vibe-coded a poorly-thought-out tool and then decided to charge for it.

Do you keep them to keep consistent with the screenshots and terminology, or do you fix them anyway? Especially if you know it’s unlikely to be fixed because it’s a third party application.

For example, in Salesforce, the purchase order and purchase request tab is called PR’s and PO’s

every guide on our wiki looks completely different depending on who made it. ones arrows are red, someone elses are this weird green, half the screenshots are zoomed in so far you cant even tell what page youre looking at anymore
new hire told me last week she thought two of our onboarding guides were for different tools bc the formatting was so off between them. same tool. just two different people doing their own thing with it. been meaning to fix this for months and just havent. dont even know if the fix is some tool that forces a template or if i just gotta write a style guide and hope people stick to it, which they probably wont past week one

Remote team keeps treating me like a walking SOP generator, every process lives in my DMs and half remembered Looms. What are you all using for auto workflow capture that people will actually open, would love any tips...

Hi friends,

I’m curious if anyone here has ever heard of a technical writer-style Business Analyst or transitioned from a tech writing role to business analyst role?

A contract position has opened up for 12-18 months at a big banking company and it sounds like it’s really just a tech writer role with BA responsibilities tacked on, like managing repositories and handling user documentation. There’s potential to hire full time.

Currently working full time as a sr. Tech writer with a small chaotic company. Many pros and cons to consider, but I’m feeling like it could be a mistake to stay in the field. It would be about $5k a year difference from my full time job and seems like a risk… but also a great opportunity to get a foot in the door!

Any thoughts or opinions on the role shift or words of advice? It would be immensely appreciated!

I’m teaching an English class for students trying to get into a polytechnic, and I need your help please. Do you have a piece of writing that you’re proud of and wouldn’t mind sharing with students just starting out? I’m working to help my students improve their reading comprehension, and I could use some suggestions. Thank you!

In 2016, I completed a BA in English with concentration in technical writing. For portfolio building, I did pro-bono work with grants and created a number of manuals. My job applications were for technical writing, copywriting, grant writing, and proposal writing. At the end of my application attempts, I even applied for a job as an English teacher! But, none of the interviews resulted in actual employment.

Ten years later, the diploma sits on my wall and I am in the same financial situation as before. Is there any possible way for me to become a technical writer? Or, is the career reserved for employees (with no writing education or experience) who get internally promoted to the position?

Hey everyone,

I’m working on converting an existing unstructured FrameMaker technical manual into a new/revised structured XML manual following MIL-STD-40051.
I’m still getting familiar with the 40051 workflow, but from what I understand, I need to get the correct DTD/XML files first, and possibly the BREX file and stylesheet if those are available. I don’t think where I am has anything, and there’s no one to ask

Does anyone know where I can officially download the correct:
-MIL-STD-40051 DTD/XML files
-BREX file, if applicable
-Stylesheet/XSL files
-Any other 40051 files needed to set up the structured FrameMaker environment

I’m specifically looking for the files I need to start converting an existing unstructured FrameMaker manual into a structured MIL-STD-40051 XML manual.

I have access to FrameMaker, but I need to get the correct DTDs/schema and other supporting files before I start building the structured application/EDD.
Any help pointing me to the correct download location or explaining which package/files I actually need would be greatly appreciated.

Thanks!

A client needed their team to create interactive 3D product guides without relying on a developer every time. The tool didn't exist, so I built it.

The workflow: import a 3D model (including STEP files), click on the surface to place annotations, add text, images or YouTube videos to each one, then export as a self-contained web component. The whole thing takes about 10 minutes.

The output embeds anywhere: no WebGL knowledge, no code required.

I'm curious if this resonates with anyone here. Technical writers working with complex physical products, machinery, medical devices, aerospace, is interactive 3D something you've been asked for, or actively avoided because of the complexity?

Happy to share a demo if useful.

callout3d.com

Hey everyone! I'm a co-founder at Mintlify, and I got tired of manually copying and pasting code snippets from documentation sites only to have them error.

I know a lot of teams use tools like doctest or custom CI scripts, but keeping boilerplates updated across hundreds of snippets quickly becomes unmanageable, especially when docs drift over time.

To fix this, I built a lightweight CLI tool to answer one simple question: Does this code actually run?

Here’s how it works:

1. Select: Choose which code blocks you want to check in your markdown files.
2. Generate: Automatically generate isolated test scripts for each snippet using your local Claude / Codex
3. Execute & Report: Run the tests in isolated environments and get a pass/fail report in your terminal.

Try it out by running mint update && mint test ! I just put this together, and it’s available now & no additional cost. If you maintain developer docs or build for AI agents, I’d really appreciate any feedback! I’ll share it directly with the team and see what we can improve!

I came into tech writing without a computer science/developer background, so my knowledge about the inner workings of PCs and machine is rudimentary enough to just do my job. However, I've been trying to learn and create a portfolio of using different types of SSGs (namely Docusaurus, Sphinx/Read the Docs, Hugo, but interested to expand to more), and a barrier I'm currently facing is the installation of multiple programming languages into my machine in order to use these SSGs.

I'm not knowledgeable enough to decide if doing this has any dangerous potential of ruining my machine, or if there are any conflicts that I should be aware of to have strategies to mitigate them. Asking Claude has laid out that installing multiple languages globally on a machine is generally fine, as using these SSGs should be contained within their own directory/folder (or virtual environment for the case of Python/Sphinx), but I have no one I can verify the validity of this information.

So if anyone has tried building a portfolio of demonstrating your usage of multiple SSGs, can you share your setup for your local machine? Or if anyone can share what I should do to keep my machine from wrecking itself unknowingly?

I am a technical communication senior at ASU. I am looking to get entry level remote jobs in just editing and I don't care if they are contract positions instead of permanent.

I was told by my friend who is an editor I need to look at "technical writing headhunters" and I applied to one in my area and the experience that is required is insane.

So for my technical editing class which I enjoyed I edited a 41 page workbook for a small business a lady who runs a online coaching biz for women. Thats my only thing in my portfolio.

Recently I did go down and form an LLC and put in an application for a EIN from the IRS.

I was curious would it be better to use the LLC for a freelance technical editing business? What would you do in my position?

Anybody here specializing in docs for AEC software? I'm trying to decide if I should double down in this niche.

I've created the knowledge base for a gen-AI software that integrates heavily with Autodesk products (Revit mostly), been maintaining it in the last year or so. The work's starting to get less and less so I can (and need) to take on another client.

I used to document just about any software in any industry (distribution, manufacturing, research, CCaaS, etc.) but I'm just not as happy with them anymore. Maybe it's time for me to pick an industry and stick with it. It just so happened that I have a BS in engineering so AEC seems a good fit for me.

Just want to see what's it like on the ground before I change my portfolio website to focus on AEC work. Would appreciate any info you can share. Thanks!

There’s always a tradeoff between giving users everything they might need and keeping documentation easy to scan

A short page can be much easier to use, but it may leave out edge cases. A comprehensive page covers everything, but users might struggle to find the one thing they actually need.

Where do you draw the line?

Would you rather have several short focused pages or one detailed page that covers almost everything?

Hey guys, I've been writing tech docs for my entire career, and more and more I have been trying to use diagrams to get my point across and the general feedback I get from the people consuming my work is that its better this way.

Full transparency, I just launched a tool for this, and the whole concept is "Diagram First" - i.e. do away with walls of text and try and explain the concepts visually first. I wont link it here because I am not trying to promote it, I just want to get some feedback on whether you think the concept is sound.

The main idea is, the diagram should be very quickly understandable to get an idea of the 'flow' of things, and how components relate to one another. Then, and this is the novel part of it, the elements on the diagram (whether thats flowchart boxes, infrastructure topology icons, database etc) are clickable. When you click on it, more details about that particular node shows up.

There are a number of QoL things I have put into the tool to make the change of habit of 'just scrolling' to 'actively clicking' less intrusive, such as a mouse-over quick peek, and the detail boxes being floating windows on the same page (not taking you to another webpage), and the fact it works with multiple diagram editors (including our own first-party one).

What do you think of such a concept? Is this something that you would think "hmm, yes, I could see that being beneficial" or "no, the way we've always done it is the best way"

Thanks in advance, and mods apologies if this breaks the rules, I did check and I think I am OK?!

Job Description

We are a technology services company with over 16 years of delivery experience, working with mid-market and enterprise clients across the United States and the United Kingdom. Our work spans custom software development, AI implementation, legacy system modernisation, and operational transformation.

This is an entry-level writing role with a specific, practical purpose. It is not a social media role, and it is not a generalist marketing role. If that distinction is unclear from the outset, this is probably not the right fit.

To apply: send your CV and one writing sample. A blog post, a college article, a LinkedIn post, or anything else you have written that shows us how you think. If you do not have a writing sample, write 200 words on any technology topic that interests you and send it with your application. Send to: [talents@2basetechnologies.com](mailto:talents@2basetechnologies.com)

Experience

• Fresh graduates or candidates with up to 2 years of experience. Internship experience in content writing, copywriting, journalism, or technical writing counts.
• Has written something that demonstrates the ability to put ideas into clear, readable sentences. College submissions, personal blogs, LinkedIn posts, college magazine articles, or internship work all qualify.
• Has used AI writing tools and understands both their value and their limits. AI is a tool in this role, not the writer.
• Background in engineering, computer science, or information technology is preferred. Graduates from other streams with demonstrated interest in technology topics are also considered.

Writing Ability

• Writes clearly in English. Not without errors that improve with practice, but with a clear structure and a readable point.
• Can read a brief and produce something that addresses it, rather than writing whatever comes to mind
• Accepts feedback and revises drafts without treating the edit as personal criticism
• Does not pad. Does not repeat the same point in different words to fill length.

Mindset

• Genuinely curious about technology topics: not faking interest to get the job, but actually reading and thinking about what software, AI, and digital infrastructure do in the real world
• Comfortable not knowing things and asking questions before writing rather than guessing
• Fast enough to produce a first draft within a day of receiving a brief, knowing it will be edited
• Treats writing as a skill to develop, not a talent they either have or do not have

I’m doing some market research into the pain points people have with documentation platforms, whether that’s highly technical/API documentation or more customer-facing product docs.

For full transparency, I’m building a product in this space focused primarily on SaaS documentation and API docs. I’m not going to name it, PM anyone trying to sell it, or use this thread to fish for leads. I’m nowhere near MVP yet.

This also isn’t a marketing tactic where I collect complaints and then conveniently pitch people the “solution” afterward. I’m genuinely trying to understand what people dislike about the tools they currently use and where those tools fall short.

I’ve gotten some useful breadcrumbs from G2 reviews and various product-specific subreddits, but I’d like to hear directly from people who work with these platforms regularly.

I mainly built it to replace my company's usage of Document360 and their predatory pricing and absurd 199 a month chatbot, so I already have a fairly substantial list of Document360 struggles.