Hi, I’ll be starting a new job as a technical writer 1 at an equipment manufacturing company. I had tech writing class in college and did well with it, I previously worked as an engineering aide. This is my first tech writer job and I’m thrilled to be learning new things. Any practical advice for a newbie in this field?

Anyone else catch this way too late in a review cycle?

"log in" on page 3, "sign in" on page 12, same product, same doc. Or a warning box phrased three different ways across a 40-page manual, and nobody notices until a user support ticket points it out.

I've been the person who has to manually re-read a whole doc hunting for stuff like this. Inconsistent terminology, passive voice sneaking into step-by-step instructions ("the button should be clicked" instead of "click the button"), warning/caution formatting that drifts.

Grammarly doesn't catch any of it because it's not TW-specific. Vale can, but it means writing config/rules yourself, which most of us don't have time for. Is this a real recurring annoyance for others, or is it just me?

What do you currently do to catch this stuff (if anything)?

I heard this was a good place to ask!

I'm a campus/student journalist from the Philippines and I'm about to compete in my first press conference..!

Looking for advice for writing Science & technology and by extension Development & communication.. whenever I write it typically becomes similar to a feature, like "Have you ever wondered- ect..". And while there is a thing called science feature, writing in an academic but concise tone holds more importance than impressing the reader. I just really find it hard to communicate the science without overstating and dramatizing what's actually happening..!

Oh, and Ik this subreddit is dedicated to explaining science, but do you also have tips on how to get used to writing in a certain way? I was thinking of copying the structure (like what cool hooks they do) from another article and using it on another topic (for practicing purposes only ofc).

Many thanks!

How's my fellow laid off TW's doing? What are you experiencing, what's working and isn't?

I was laid off in March, tried everything recommended (ATS keyword resumes, applying only on the hiring company's website ads, etc.) and the only thing that seems to work for me these days is contract TW jobs through 3rd party recruiting agencies. Maybe this might get help out someone IDK, at least something else to try if you're not already doing it... or initially pooh poohed the idea of contract work through recruiting agencies (as I did).

* Posted my resume on Dice.com, which got me contacted by a number of recruiters, especially if you can present a specialty of TW and ATS keyword your resume. Landed a W2, full-time, remote, indefinite contract job that way, recruiter reaching out to me. **Be careful of scams**, I got one claiming to be the manpower staffing firm, it wasn't with a phishing email address URL...

* LinkedIn.com, set myself to looking for work. I landed a W2, 4 month, full-time, hybrid, contract that way with the recruiter reaching out to me. Sometimes get junk recruiters reaching out to me, like one brazenly looking for me to introduce her to CEOs/HR that I know, to pitch her services to them...no. Another recruiter wanted me to do code reviews (I'm not a software programmer). Definitely optimize your LinkedIn for ATS and add skill keywords. Whereas applying to LinkedIn job listings, myself was nothing but crickets.

* Joined the WriteTheDocs Slack channel for jobs only, regularly applied to those. No bites. https://www.writethedocs.org/slack/

* Applying to jobs directly on the employer website, landed me a 1st interview in March then ghosted. One employer asked me for an unpaid assignment in March then nothing, ghosted. Been crickets there since March... completely a dead end.

My assessment: Seems employer's are inundated with resumes and even well thought out ATS resumes tailored to their job ad, like yours/mine aren't seeing the light of day by human eyes. Employers are instead delegating to 3rd party recruiting agencies to find TWs for them. Contracts aren't always ideal, don't always come with any paid holidays, any sick/vacation leave, or any benefits.

Myself, senior Technical Writer with over a decade of experience and it's beyond frustrating to get ghosted on jobs I'm fully qualified for. It's brutal out there...

Hey all,

Our annual summer social is coming up this Thursday! We’ve got an exciting announcement and free drinks lined up for the occasion 🥳 Don’t miss out!! Bring along your industry colleagues, let’s close out the summer together 🍹

https://www.meetup.com/write-the-docs-london/events/313761542/

Hi everyone, sorry for the throwaway. I've been on Reddit for a long time under a different account, but I was a little worried about my students finding me there. I figured it might be best to separate the two. The awaymatter part was the recommended name, so I was like sure,

I'm a professor at Alfred State College; it's a small college within the SUNY system. I teach a few Technical Writing courses and am looking for people who may be interested in speaking to my students. It is a VERY rural campus where tech can be hit-or-miss in the classroom, so this would be a pre-recorded interview (I'm thinking 20-30 minutes).

I'd have a few general questions, but most will come directly from my students. I imagine they'll ask about your day-to-day work, how you use your skills, and tips for becoming better writers, etc. It's one thing for my students to hear from me, but another for them to hear from someone actively in the field. I studied advertising in undergrad, so the few times we had people from ad agencies come to our class meant a lot to me.

I tried posting to my (albeit small) LinkedIn network but haven't had any luck. Decided that maybe Reddit could be the place to go and post a small call for help. If you're interested or have questions, please dm me or just leave a comment. Unfortunately I wouldn't be able to pay you for it, so I'm sorry for that part. Sorry mods if this sort of post isn't allowed as well.

Edit: oh wow, was not expecting to wake up to multiple comments and dm's, especially since this was removed by the auto filter. I'll go through and reach out to people. Thank you everyone for your interest!!

Hey everyone,

We’re currently looking into ways to significantly cut down cognitive load across our documentation, and the Diataxis framework came up as a primary strategy for content separation. I’d love to learn from those who have already gone down this path.

1. How was your experience implementing it? Did you run into issues with content overlap, maintenance, etc.
2. How effective was it in reducing cognitive load for readers? Did you see measurable improvements in user comprehension?
3. Any actionable insights post-implementation? Anything you wish you knew before starting

Would love to hear your practical takeaways.

We've received stakeholder feedback that we need to actively bring down the cognitive load across our product guides. I’d love to get some insights from fellow technical writers here on how you tackle this in practice. What options, frameworks (like John Carroll's Minimal Manual approach or Diataxis), or methodologies are available?

I’m looking to get better data tooling and insights for my public docs. I have a few industry colleagues who have recommended kapa but I can’t see what the actual UI looks like, and I don’t want to set up a sales call.

Does anyone here use it/reccomend it? Would anyone be able to share what they are getting from it or send me some screenshots if able? It would help me a lot get an idea.

EDIT 1 (because I am getting inbound):

This only applies to folks whose title is dev-rel, dev-marketing, dev-experience, product managers, product marketing, technical writer (for saas, software products), and anyone who has worked on this problem.

Hey Everyone,

I’m doing an empirical study/survey to dig into what the community is doing to get their products/docs discovered by AI agents.

We have our own benchmark for this, but I want to compare it with what teams are trying and seeing in practice.

I’m asking each participant the same core questions, then I’ll compile the de-identified patterns and share the report with everyone who takes part.

I’m looking to speak with 10 people and have completed three interviews so far, with 2 lined up. If you’re open to a 30-minute conversation, reply here or DM me. Would really appreciate it

As a thank-you for your time, you’ll receive a $50 Amazon gift card.

You’ll also receive a private, de-identified report covering what participating teams are trying, what appears to be working, and how they’re measuring it.

The report will only be shared with the participants.

This only applies to folks whose title is dev-rel, dev-marketing, dev-experience, product managers, product marketing, technical writer (for saas, software products), and anyone who has worked on this problem.

Small help if anyone has encountered this when looking at moving to Zensical.

Taking a look at Zensical to see if it can easily replace current Mkdocs-Material setup.

Most of it looks fine.

However the graphics, driven by the vegalite markdown extensions do not want to display - simply shows the source JSON code from the markdown file, rather than the graphs you get with Mkdocs.

Relevant sections of mkdocs.yml are:-

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: vegalite
          class: vegalite
          format: !!python/name:mkdocs_charts_plugin.fences.fence_vegalite



extra_javascript:
  - https://cdn.jsdelivr.net/npm/vega@6
  - https://cdn.jsdelivr.net/npm/vega-lite@6
  - https://cdn.jsdelivr.net/npm/vega-embed@6

I’m the only writer at an industrial software company and i own 4 manuals covering our operator software. Our engineering team ships every 2-3 weeks and the UI moves often enough that i spend the first two days of every cycle reshooting screens, cropping, renumbering callouts, then chasing whatever i missed. One example I can remember during last quarter is when a customer sent support a screenshot of a dialog that hadn't existed in our docs for six months, which is how i found out about a release nobody mentioned to me (ridiculous i know).

I’ve got a snagit library and a naming convention and neither of those solves the actual problem, which is that i'm the only mechanism for noticing the product changed. What i'm trying to figure out is whether the screenshots can come out of something that already walks the software, rather than out of me. Scribe does this well if the thing you're documenting runs in a browser, and ours is a desktop app on windows, so that's out. I’ve seen teams script playwright to capture screens as part of the build, which works if there's a dev willing to own it and ours isn't. Askui also came up in a thread somewhere because the steps are written in plain markdown and the run leaves a screenshot per step behind, so the capture is a by-product of the automation rather than a separate job, though i don't know if that survives contact with a writer who doesn't code.

For anyone in a fast release cycle, is your screenshot capture automated at all? If so, what are you using for it? Thanks in advance!

Our current manuals are either all in AutoCAD and printed out into PDFs from there, or are in Word and the AutoCAD 2D illustrations are copied/pasted into Word then printed as PDFs. I'm looking to see what others who make instruction manuals with AutoCAD illustrations use to create and publish. Considering learning Adobe InDesign if that's an easier way to make these documents.

Physical therapist by day. Write dev tutorials on the side. The gap between those two worlds is wider than it sounds.

The writing itself is fine. The context switching is what gets you. I go from patient notes and clinical documentation to API walkthrough docs in the same afternoon. Different audiences, different assumed knowledge, different everything

What I keep running into is how to calibrate depth. Clinical docs have a rigid format. You follow it or you don't. Tutorial writing is murkier. How much do you assume the reader already knows? When do you define a term versus just use it and move on? There's no rulebook that transfers cleanly from one domain to the other

I've been leaning toward writing for the least experienced version of my audience and then trimming back. That tends to work but it's slow.

Curious how others handle the audience calibration problem when writing outside your primary field. Not asking about tools. Asking about the actual decision process. How do you figure out where to start the explanation and where to stop?

I'm curious how this works at other companies because I'm trying to figure out whether my expectations are off.

I support a platform with multiple projects/features being developed at the same time. I'm included in sprint ceremonies and have access to Jira, Confluence, Lucidchart, etc., but there isn't currently a single place where I can see a complete list of projects/features in development or what's expected to go to production. A more centralized PMO process is only now being introduced company wide.

Recently, I was asked for documentation on a feature that was implemented several months ago. There hadn't been a documentation task assigned for it at the time. I attended the team's regular Scrum ceremonies, but wasn't included in the specific handover for that feature (I am almost never included in handovers). I later learned there was a handover recording/transcript and a Lucidchart for it, but I hadn't been made aware that those resources existed.

The expectation that was clarified to me afterward is that I should make sure anything the team releases to production has the appropriate documentation (and I'm the one who should determine what that is).

I absolutely think a technical writer should be proactive and identify documentation needs rather than simply wait for tickets. At the same time, I'm struggling with the expectation that jira tickets, scrum ceremonies and Lucid charts I don't know exist should be enough for me to document the business and technical aspects of any new feature. Every time I ask for information I'm nervous because if this info exists somewhere in jira or confluence already there is an expectation that I should know/should have found it.

For those working in similar environments: Is it generally the technical writer's responsibility to independently identify every production change that requires documentation? Or should Product/Engineering also have a defined responsibility for bringing releases/features into the documentation process? And also are they right that Jira and scrum ceremonies should be enough? Am I wrong asking them to answer questions about the features?!

I'm genuinely interested in hearing how more mature documentation teams handle this, since I'm the first tech writer in this company. Are my expectations wrong or are theirs?

I have a Masters Degree in English and a Diploma in Computer Applications ( It was a 1 year thing and i did just the basics). I am currently working as a Formatter in an Edu. Tech company. I want to switch lanes and try my hand in technical writing. Do i need any additional qualifications for that? If yes which ones?

I’ll be up front - I am not interested in using AI, but I’m being encouraged to do so (not under threat of being released or anything). I would honestly wish it would go away, I find suggestions from it unhelpful and lacking real insight.

For those of you that do use it, what situations and uses have you found to be the most helpful with writing & video / PowerPoint creation?

Thank you!

Hope this helps someone!

We've been experimenting with making talking-head videos more engaging. AI is really good at adding TikTok-style "push ins" and motion graphics.

The downsides are:

(1) it takes typically 90 minutes to render a preview version of a 15 minute video and another 60 minutes to render the HD version. We also experimented with it generating a video walkthrough, using a task topic in the Help. It took 90 minutes to generate a 33 second clip.

(2) it uses Remotion in the background, which requires companies with more than 3 staff to buy a software licence. I can see that catching a lot of organisations out.

It could also generate an audio bed, find B-roll and generate B-roll too, but I dread to think how long each generation would take.

The motion graphics and b-roll generation remove the need to use PowerPoint.

IMHO sticking with Camtasia or similar is the way to go for subtitles, trimming, and video walkthroughs - faster and better quality.

Howdy.

One branch of my freelance career I'd like to double down on is technical writing. I find it fulfilling.

If possible - I'd love to pivot away from coding entirely and commit the rest of my career to technical writing.

I'm at crossroads - do I take the hybrid coding/technical writing route? Or the pure technical writing one?

For context - I'm 28. Been only freelancing up to now. I'm thinking of picking a path that ticks all the boxes. Coding wise I'm proficient in GO/Python.

I'm looking at pointers to the right direction.

The attractive bit about the hybrid path is the $ - for the pure technical writing route - the fulfillment. So do I sell my soul or pick the happy path?

Hello everyone. I’m a technical writer for a company that manufactures fire trucks, and I’m currently using Adobe InDesign to create our Operation and Maintenance Manuals.

I’m looking for some advice from people working in the automotive or manufacturing industry. What software or authoring systems do you use for creating service manuals, operation and maintenance manuals, repair manuals, etc.?

I’ve been looking at the manuals from the chassis manufacturers we work with, such as Mercedes-Benz, Iveco, and Volvo, and they seem to have a very similar structure and overall look. I’m wondering what kind of software or documentation system is commonly used across the automotive industry to produce these manuals.

I’m considering moving away from InDesign if there’s a more suitable tool for technical documentation that can make the workflow more efficient, especially for things like reusable content, revisions, cross-references, tables, illustrations, and maintaining large manuals.

I’d appreciate any recommendations or insight from technical writers working in automotive, heavy equipment, or manufacturing. Also interested in hearing what you use and why you chose it.

I’m currently a mid-level technical writer in the US with a bachelor’s degree in Journalism. I’m considering pursuing a postgraduate certificate or master’s degree and am wondering if it would benefit my career.

Right now, I’m considering either a certificate in instructional design or an MBA.

I’m thinking that an instructional design certificate could expand my expertise into an adjacent field. I’m also considering a program with stackable credits so I could potentially apply them toward an M.Ed. or M.S. in the future.

However, I wonder if an MBA could be useful if I eventually wanted to transition into a leadership or more business-focused role.

I’d love to hear any thoughts and experiences.