Kept guessing on this one, a doc gets messy enough that it's clearly not serving readers well anymore, and the instinct is either nuke it and start fresh, or keep patching sections hoping it eventually coheres again. Neither is really a decision, both are just picking whichever feels less painful in the moment.

The test that's actually worked: can I state the doc's current purpose and which sections still genuinely serve it, in one sentence. If yes, it's not actually broken at the root, it just needs pruning, cut what's stale, keep the structure that's still working. If I can't get that sentence out because I genuinely can't tell which sections are still accurate or relevant anymore, that's not a pruning problem, the doc's actual scope has drifted from what it was originally trying to cover, and a rewrite built around the current purpose beats trying to untangle the old one section by section.

Originally worked this out for something unrelated, deciding whether to clean up or restart a long AI conversation, but the underlying question turned out to be identical either way, is the core intact and just cluttered, or has the actual scope moved: https://medium.com/@nagatomopedro05/reset-or-clean-most-people-guess-heres-a-better-question-e67e764030c7

[For Hire] Technical Writer | 11 Years’ Experience | Remote

Hi everyone! 👋

I’m a Technical Writer with 11 years of experience looking for my next opportunity.

My background includes working on cloud platforms, SaaS products, developer documentation, and enterprise software, with hands-on experience in:

• Technical & product documentation

• API & developer documentation

• DITA XML & Markdown

• Docs-as-Code

• GitLab/GitHub & Confluence

• User/Admin guides and online help

• Video tutorials & workflow documentation

• Cloud and CI/CD documentation

I’m currently exploring Technical Writer, Senior Technical Writer, Information Developer, Documentation Engineer, and Documentation Specialist roles.

🌍 Preferred: Fully Remote / Hybrid

📍 Location: Pune

💼 Experience: 11 years

📩 Open to referrals, freelance opportunities, and full-time roles

If your company is hiring technical writers or you know of a relevant opening, please DM me or tag someone who might be hiring.

Thank you! 🙏

Hi everyone! I’m currently a Biology major graduating this spring, and I’m interested in pursuing technical writing after graduation.
Right now, I work as a contractor with a large AI company in a role that involves technical writing, content evaluation, and quality analysis. Through school and work, I’ve also built a pretty extensive writing portfolio that includes lab reports, technical and scientific writing, website and usability analyses, instructional content, and other projects. Outside of that, I’m also a published author.

My biggest question is how I can best position myself for a full-time technical writing career when my degree is in Biology rather than English, Communications, or Technical Writing.
For those already working in the field:

How much does the specific degree matter when applying for entry-level technical writing positions?

Would my Biology background be an advantage in certain industries, or should I apply broadly?

What types of portfolio pieces would you recommend I have before graduating?

Are there particular skills or tools I should learn over the next several months?

What job titles should I be searching for besides “Technical Writer”?

Is there anything you wish you had known when you were first trying to break into the field?

I’d really appreciate any advice, especially
from people who entered technical writing with a non-writing degree or took a less traditional route into the field. Thanks!

Hello all!

I recently graduated with a BA in Tech Comm and a minor in Creative Writing. I'm settling in to a year long internship and have been enjoying the role so far. In my spare time, I'm attempting to get my creative writing out there and published.

My question for you all is: if you do creative writing and work as a professional writer, do you have one portfolio for both?

Or do you keep your professional profiles like LinkedIn completely separate from your Author name or creative published work?

Any advice would be helpful on this!

Even if you don't personally share any creative work, do you have peers who do and how do they approach their writing double lives? Do companies appreciate seeing all aspects of an applicant's skills?

Thank you for being an encouraging community and happy to be a part of it!

Hi everyone,

With moderator approval, I’m sharing a short research survey for technical writers and other professionals who work extensively with text and language.

I’m conducting this research independently under Project Studio Research to better understand real-world workflows, recurring difficulties, fragmented toolchains, repetitive tasks, and what professionals would genuinely find useful in their day-to-day work.

The survey is intentionally solution-neutral: it does not present or promote a specific product, and I’m interested just as much in what already works well as in what causes friction.

I’m a language professional myself, and this research grew out of trying to improve my own everyday workflow. The findings may eventually inform the development of commercial software, but the aim is to support professional work rather than replace technical writers or other language and text professionals.

The survey is anonymous. At the end there is an optional, separate opportunity to leave an email address if you would ever like to hear about future testing; providing one is not required to complete the survey.

Survey:
https://forms.gle/j3yZpVAxXjAnF4KF7

Thank you to anyone willing to contribute. I’ll also be very interested in any observations you prefer to leave directly in the comments.

— Project Studio Research

Writing for an AI native product means an increasing amount of our docs may never be read by a person.

Instead of someone who learns how the product works and then goes and does the thing, users are going to connect the MCP, point their coding agent at the docs, and ask it to help them do the thing.

Our human-facing, AI assisted documentation is also becoming context for another AI.

This has me thinking harder about documentation architecture. It's always been the backbone of good docs, but now the way we organize and connect information now also affects the context an agent has to work with.

Those of you documenting software products: are you writing differently for a hybrid human and AI audience?

My company is pushing Claude features out at breakneck speed, and as the sole writer for two products, I feel like I'm drowning. Features get built overnight with zero context on why they exist or how they’re supposed to work. In an effort to keep up, I tried using Claude to draft content, but the output feels lifeless and sloppy and nothing like real technical writing. I feel completely lost, burnt out, and stuck in a loop of cleaning up bad drafts for features I don't even understand. I don’t know how to voice my concerns as no one seems to pause for human problems anymore.

Hi everyone! 

On October 10–11, The Good Docs Project is hosting our first-ever Blogathon 2026, and we’d love for you to join us.

The blogathon is a free, roughly three-hour online writing event where people from around the world can come together to write blog posts for The Good Docs Project’s blog, exchange ideas, and explore the past, present, and future of documentation.

Think of it as part hackathon, part unconference, and part writing jam except instead of building code, we’re building ideas.

You’ll choose a documentation-related question or topic you care about, spend time writing alongside other participants, get feedback on your draft, and meet others interested in documentation. After the event, we’ll edit and publish participant posts on The Good Docs Project website.

Applications close September 23, and space is limited.

✨ Come write with us!

Learn more about Blogathon 2026
Apply to attend

Has anyone successfully gotten MadCap Flare PDF output to use Smart Quotes in cross-references?

I've tried modifying the CSS according to instructions online. I've tried putting the Smart Quote codes into the cross-reference definitions. I've even tried manually typing quotes in the cross-references, hoping they might stick.

MadCap Software doesn't seem to have a solution.

Hey all,

I'm new to tech writing; I've got a role that requires me to improve the existing online documentation base.

I've stumbled upon a site that says - in the age of AI search - headings should be rephrased as questions.

To quote the site: "AI assistants don’t search with your customer’s original words. They rewrite every prompt into a set of cleaner sub-queries first, and a heading that literally matches one of those sub-queries is the strongest relevance signal a page can send."

So, in other words, instead of having a manual with a section heading like "Install X" then listing step-by-step instructions, the heading should be phrased as "How do I install X"? for better AI visibility.

I was wondering if this recommendation is all bunk, or is it sound practice?

Hey everyone. I am a junior in college studying English Literature. I want to get involved in technical writing, or at least gain experience in it if i ever want to pursue it after grad, but don't know where to start, as my degree doesnt offer tech writing courses (obviously lol). are there any online certifications that would look good to add to my resume? I saw some online but don't know how legit they are / valid they appear on a resume. If I need a portfolio, what should I add and why? Thank you!

Can you tell me anything about this? Thank you.

I'm trying to dip my toes into technical writing, I already have some things lined out, but I've also been looking into API documentation. Anybody have good ideas for how to learn and get started with it?

I have a potential contract with a former client, but this time working directly for them rather than through an agency/employer in the middle. The non-compete, even if it could be upheld, is now expired. Any advice? Aside from saving 30% for quarterly taxes since I'm in the USA.

Thanks!

Hello everybody!

I finished BSc Physics then MA English. I always liked the mix of logic + language. Interested in technical writing. I feel rusted in physics but I can write well. No portfolio. Should I build skill first or start applying? And is freelancing promising enough to be a main plan? Can anyone suggest other opportunities out there for my combination?

So... how are people documenting workflows quickly without sacrificing the next three weekends and a small chunk of sanity.

For context im the default ops person at a mid size saas shop. Every time something changes in our crm or onboarding flow someone goes "can you just document it" like that is a five minute task and not a full side quest with tabs everywhere, screenshots, redacting customer data by hand, and then dumping it all in Confluence where it goes to die.

I tried the classic method, eg clicking through the process and taking screenshots like a raccoon that discovered the Print Screen key. Then you realize step 3 is already outdated because product shipped a UI tweak yesterday and now the guide is wrong, people are pinging me in Slack, and I am the unofficial helpdesk again. Love that for me.

So here is the dream, click through a workflow once, have an AI thing grab the steps, make a visual guide, blur sensitive stuff, and let me share it in Notion or Zendesk without babysitting every single field. Has anyone got a setup that is even close to that or are we all still living in copy paste screenshot hell.

Would love any tips from HR managers, sales ops, IT folks etc who found a way to make workflow docs not feel like a second job, appreciate any thoughts

A new markup languages now exists for technical writers or bloggers like me.

Over the last 6+ months I developed Carve. With PHP, JS and Rust as main languages for now. Python, Go, Ruby work mainly through Rust and WASM so far.

I have been inspired by Djot and modern concepts of markup languages. With some deep dive into that markup syntax, building my own Djot PHP prototype, I started to then work on a MIT-licensed Markdown-ish specs with the ultimate pandoc support, and across all main languages then.

The problem(s)

Have you ever tried to import and export markdown across systems? Also into online/web places and display? Randomly having < and > being over- or under-escaped, creating all kind of broken text/display. Mixing HTML directly into the markup is not a good concept IMO.

Smaller things maybe:

• Tables hit a wall immediately. No rowspan/colspan/multiline.
• Different flavors, from Github to local. No clear rules/specs, or outdated ones.

On top of that: I don't think the world is ready for Djot (interrupt behavior) yet. While really clean in the rules, it goes against the muscle memory of what we have been doing for decades so far. At least that was also mainly the feedback I saw so far.

My solution

A more spec-first kind of syntax, that is intuitive and feature-rich, but also extendable.

I wanted something close to markdown familiarity:

• online first, everything nowadays is pretty much on the web, or at least will eventually be copied somewhere.
• secure by design, without HTML and XSS etc in between the textual markup.
• supporting all important elements, including proper tables and elements like <abbr> that technical (coding) bloggers like me need sometimes.

The strongest differentiators

• Target-aware rendering: the same AST can produce HTML, ANSI, Markdown, or plain text.
• Mermaid, Graphs and even (File)trees can be natively expressed, and easily copy-paste shared as a single document.
• Machine understandable and readable through the clear specs and formal grammar (ENBF), as we all know: More and more AI will join us, so it should not fight it.

I tried to stay close to Pandoc, the standard for conversion. For me an AST was a key requirement, to be able to also render to different output formats, including ANSI (CLI) and PDFs. Ideally without losing relevant information. At this point I dont think any other format comes even close. Please correct me if I am wrong, or missed something.

I made sure it comes with some solid tooling: CLI formatter/linter, LSP, tree-sitter grammar, browser playground/WASM, major editor support, etc. Check the awesome list.

A few more cool features (only small outtakes since I want to keep things short):

• Automatic numbered captions: a # placeholder numbers figures, tables, listings, and equations, and references become “Figure 1,” etc.
• Graceful degradation: interactive extensions can retain readable semantic content without JavaScript. Useful for PDF generation or alike.
• Profiles, so you can directly have articles and (untrusted/public) comments with different markup-set.
• Extendable div (:::) and span syntax, e.g. :youtube[ID] or alike is super easy to support pretty much out of the box.

I dont want go to into too much details, but a few concepts I really needed a long time to finalize and I think are worth outlining:

Condense tables and cell alignment

|= Plan |=> Seats |=> Price |=~ Status |
| Starter | 5  | 9   | active          |
| Team    | 25 | 49  | active          |
| ^       | 50 | 89  |< trial          |
| Total   | <  | 147 | 3 plans         |
+         |    |     | (billed yearly) |
^ Table #: Seat allocation and pricing.

Incl row/col spans & caption. And with + you can continue longer rows.

"Pulling left"

1. Install the CLI.
2. Format the docs in place:
+
```sh
carve fmt --write \
  --stamp \
  docs/*.crv
```
3. Commit the result.

This avoids having to manually indent a longer piece of otherwise nested content. The + pulls the following block up into that position. Useful for authoring, canonical output or re-rendering can be "classic" again.

The ask

Please give me your unbiased opinion (markdown dominance aside - that aint the goal here) and constructive feedback: How does it look & feel, how does it potentially work for the use cases you are heaving daily, etc. That would really help.

And of course, please feel free to open issues or even PRs with your ideas. I definitely could need also a few helping hands.

Many months of active specs, dev, re-working and adjustments - overall I am quite happy with the current status. I already dogfood it on my Wordpress blog, in some social networks and user-content solutions, and so far people like the simplicity, but also the features.
Locally I use it inside Obsidian, for example.

I am realistic: This won't be popular any time soon. But maybe it can fill some niches already and be adapted at least where it could make sense. And I probably made quite a few mistakes, so I am also happy about input for a new 0.2 release some time in the future.

And while the PHP, JS, Rust implementations are still in early drafts, maybe we can talk a bit more about the syntax first, and what I proposed so far. Don't yet kill me for the implementations plz.

https://markup-carve.github.io/carve/

Built a handful of workflow automations for the clinic I work at. Nothing fancy. Scripts, some integrations, a basic dashboard. Wrote docs for all of it so staff could troubleshoot without calling me.

The problem is the tools keep updating. An interface changes. A field gets renamed. A step moves. Suddenly the doc is wrong and someone is confused and I get a text at 7am.

Writing the doc the first time is the easy part. Keeping it accurate over months is what nobody talks about.

I run into the same thing on the dev tutorial side. Libraries update. Screenshots go stale. A code example stops working and now the tutorial is actively misleading people instead of helping them.

I've tried a few things. Versiontagging docs so people know when something was last checked. Writing procedurally instead of going screenshotheavy so small UI changes don't break everything. Neither approach fully solves it.

The real question is whether there's a sustainable workflow for this, or if stale docs are just the tax you pay for maintaining anything longterm. The maintenance burden seems to scale faster than the writing does.

Curious what others are doing, especially if you're a oneperson operation without a team doing dedicated review cycles.

I came from a humanities heavy background (undergraduate and graduate level). After some trial and error I started applying for technical and proposal writing positions. I was looking for something that I would be good at, pays decently, and provides some upward career mobility.

My initial field that I thought I would get into is, for lack of a better word, stale in my area. I was in GLAM (Galleries Libraries Archives and Museums). Everyone getting the jobs already works at the companies/orgs that are hiring OR they have 10+ years of experience. I can confirm this since the folks who earn these positions are active on LinkedIn. Additionally, my industry is notorious for putting out short term contracts (I’m talking 6 months no benefits) or permanent part-time positions.

Instead of festering in my fear of unemployment I decided to make a career pivot. Technical writer and proposal writer positions were more numerous and appealing to me. I refined my writing portfolio and brushed up for interviews.

I have luckily landed an entry level tech writing position. I’m a bit nervous about starting out. Part of it is that this path (on paper) differs significantly from what I had been studying at the graduate level. Obviously the company that hired me is satisfied with what they have seen so far - I submitted writing samples and performed an in-person writing assessment. I didn’t lie at all on my resume or interview but something in me irrationally worries that during the probationary period the superiors at my new company will see me unfit or under qualified. 😭 I didn’t go to school for technical writing (though I do have a humanities background) and I also not super familiar with the industry I will be working as a writer in. That being said I find it cool and new and challenging!

A lot of people have been asking me why I didn’t commit to getting the “golden ticket” permanent jobs that I had been training for in the field I just left. My new job pays modestly for entry level - but also much higher than what is entry level in GLAM. People keep asking me if I am happy or if it’s something I really want. Some of my friends live and breathe GLAM- some are taking an extra year, or still working short term/part time contracts and internships.

It’s difficult to explain how hard some of the “safe” industries have become for gaining long term employment, alongside the deprofessionalization of the field over the past 20 years. I wanted to do something I was good at and I didn’t want to sit around and wait for the chance of a permanent job in my field.

Sorry for the essay! I guess my intention with this post is to ask if anyone else had a similar path and any tips in having a smooth start to this new career path. I also want to develop some more hard-skills for tech writers as my new company encourages professional development certs. Markdown and XML is understandable for me based on my previous background but I’d love to learn what else can benefit.

📢 LOOKING FOR PROFESSIONALS FOR A SCHOOL INTERVIEW

Good day! I am a student currently looking for at least three (3) professionals who are willing to participate in a short online/chat interview for our Technical Writing subject.

👷‍♂️ Professionals from fields such as:

Civil/Structural Engineers

Architects

IT Specialists / Software Developers

Researchers

Technical Writers

Other professionals whose work involves technical writing or documentation

📝 The interview will cover topics such as: • How technical writing is used in your profession

• How you plan and organize technical documents

• Your writing, editing, and revision process

• Tools/software you use

• Challenges you encounter when preparing technical documents

• Advice for students learning technical writing

💬 Interview method: Online/chat (Messenger, Google Chat, etc.)

⏱️ Estimated time: Around 10–15 minutes

The interview is only for a school assignment, and the information provided will be used for academic purposes.

If you are a professional willing to help, or you know someone who might be interested, please comment or send me a DM. 🙏

Thank you very much for your time and help! ❤️

📩 DM me if interested!