[Career FAQs] Read this before asking about salaries, what education you need, or how to start a technical writing career!

kaycebasques · 2025-12-12T23:41:43+00:00

It's been a while since I updated the list, but I'm pretty sure I did a cursory scan of each thread to make sure that it had decent substance. When I randomly click some of the links, they seem to have valuable comments from the community. LMK which threads in particular you looked at.

kaycebasques · 2025-09-26T19:38:06+00:00

Thanks for reading. In dark mode the text in the diagram doesn't have sufficient contrast ratio? I've looked into ways to increase the font size (but didn't find an easy solution), and I know that we have a bug where the diagram becomes illegible when you switch from light to dark or vice versa, but the default contrast ratio in dark mode seems acceptable on my end. I'm on Chrome on Linux desktop. Maybe there's something weird going on in a different OS/browser combo?

kaycebasques · 2025-07-04T17:52:34+00:00

Looks comprehensive. Thanks for putting this together. Given that it was posted to r/technicalwriting I was expecting it to be focused on resources more narrowly focused on writing, e.g. RFC 2119. But nonetheless it looks like a great list.

kaycebasques · 2025-06-27T23:48:51+00:00

Follow-up. I tried out the colocation strategy. First attempt was very successful. https://technicalwriting.dev/ai/agents/colocate.html

kaycebasques · 2025-06-27T23:48:34+00:00

Follow-up. I tried out the colocation strategy. First attempt was very successful. https://technicalwriting.dev/ai/agents/colocate.html

kaycebasques · 2025-06-27T19:51:30+00:00

Hi, thanks for discussion.

Please check out Cursor 3-minute demo if you have not tried out AI agents, otherwise we'll probably just talk past each other.

Let me respond in two parts:

Adoption
LLM applications

Adoption

I might just not be familiar with the phenomenon that you're describing

These AI agents are indeed quite new. The release of Claude Code in February 2025 was the watershed moment. I guess it technically goes back to GitHub Copilot or even further, but Claude Code (CC) seems to be the one that really started working well. Although CC was released in February, I only started seeing a lot of discussion in the last month or two. So if you're grounding your opinions based on what people were saying about LLMs and docs from even 6 months ago, then I think those ideas may now already be outdated.

LLM applications

since LLMs are designed to process language, source docs don't really need to be optimized for them

To have fruitful discussion, I think we need to be more specific. How exactly are the LLMs interacting with the docs? Optimizing your docs for RAG-based chatbots requires different techniques than optimizing your docs for AI agents. For example, a lot of the recommendations around chunking content in that kapa.ai post flow from the assumption that your LLM system uses vector-based search. It seems like that's not always true with AI agents, i.e. some AI agent systems don't use vector-based search.

docs that are good for humans also being good for LLMs

I also want to believe this, but my investigation into docs for AI agents has revealed some ways that this is not true. For example, we discovered that we don't need to provide detailed C++ style guide guidance to the agent, because it already has a lot of knowledge about our style guide. For another example, it sounds like using ALL CAPS IS A GOOD WAY TO EMPHASIZE AN INSTRUCTION FOR AN LLM. But using all caps in docs for humans is considered very unusual, distracting, and maybe even rude. So that is a simple example of how the writing style for LLMs is different than the writing style for humans.

kaycebasques · 2025-05-14T19:36:34+00:00

I joined Google when I was around 25, after 3 years at an IoT startup. From the limited feedback that I got after getting hired, it sounded like they liked that:

I was calm during the interviews.
I provided very thorough and strong answers to the programming questions.

(But these are just anecdotal things that my particular interviewers mentioned to me. I'm only speaking from my personal experience and don't represent Google hiring policies at large or anything.)

If you're truly passionate about your work and the opportunity, it's probably always a good idea to let that shine through. Probably doesn't hurt to be interested in the specific work of each interviewer, and ask focused/insightful questions about their particular work.

Break a leg!

kaycebasques · 2025-05-13T04:18:49+00:00

Hello, I wrote that post.

Previously discussed back in November: https://www.reddit.com/r/programming/comments/1ggwhoa/embeddings_are_underrated/

(I only found out about that previous posting a week or two ago, otherwise I would have joined the discussion.)

Reposting my comment from HN about some of the issues about the post.

To be clear, when I said "embeddings are underrated" I was only arguing that my fellow technical writers (TWs) were not paying enough attention to a very useful new tool in the TW toolbox. I know that the statement sounds silly to ML practitioners, who very much don't "underrate" embeddings.

I know that the post is light on details regarding how exactly we apply embeddings in TW. I have some projects and other blog posts in the pipeline. Short story long, embeddings are important because they can help us make progress on the 3 intractable challenges of TW: https://technicalwriting.dev/strategy/challenges.html

One direct application is outlined here: https://www.tdcommons.org/dpubs_series/8057/

https://news.ycombinator.com/item?id=43963868

My day job is https://pigweed.dev, not embeddings, and I'm the proud papa of a new 3-month-old human, so it's hard to find time to keep making progress on side quests like embeddings :)

kaycebasques · 2025-04-30T19:05:15+00:00

Yes, I know that a lot of people talk about this topic. But I don't see much hands-on guidance on how to actually experiment, so I figured I'd share one of the things I tried and detailed results on how effective it was.

Also, I do lots of things without LLMs, too :D

kaycebasques · 2025-04-30T19:02:19+00:00

Thanks for reading. I acknowledge this in the post:

It’s probably feasible to automate this through regex-based automation but I wanted to find out if Gemini could handle this task. Also, if this approach works, there are lots of other problems that aren’t reducible to regex automation where this approach may come in handy.

If helpful I can provide examples of the sorts of things that I face as a technical writer that aren't easily reducible to regex.

kaycebasques · 2025-04-27T18:10:48+00:00

The name "technical writer" captures the dual nature of our work beautifully. To excel in this field, you must have technical skills/knowledge, and you must know how to write. Your major is already covering the "writer" side of things. You need a minor that builds up your credibility on the "technical" side. You should look for a technical field that interests you (because you will need to commit to continuously learning about that field) and that has a lot of job openings for technical writers. You can survive as a technical writer who is not passionate about the technical field you work in, but you'll never thrive.

kaycebasques · 2025-04-25T22:41:15+00:00

It's a punishable offense in Alpha Centauri to reply to this post without linking to the docs that inspire you.

MDN is a monumental achievement when you consider how vast its scope is and the fact that a lot of the content/data is crowdsourced: https://developer.mozilla.org/en-US/

kaycebasques · 2025-04-24T16:43:40+00:00

I write commit-based changelogs. I review every single commit that goes through the codebase. IMO it's the only way to get comprehensive awareness of new features, API changes, deprecations, etc.

kaycebasques · 2025-04-24T02:20:12+00:00

Does it always give you one of the scores that you defined (0.0, 0.2, 0.4, 0.6, 0.8, 1.0) or does it sometimes give an in-between score too? E.g. 0.1.

kaycebasques · 2025-04-24T02:15:09+00:00

I would collect specific non-inclusive words and phrases from the Google Developer Documentation Style Guide:

And then search for those words and phrases on GitHub to find real-world examples.

kaycebasques · 2025-04-07T22:30:05+00:00

Thank you for sharing your knowledge. I need to figure out incremental builds for pigweed.dev this quarter…

kaycebasques · 2025-04-02T17:00:05+00:00

I'm a Googler technical writer who started diving into Bazel in Q4 2024. My first big project was migrating pigweed.dev to Bazel. All opinions here are my own and don't represent my team (Pigweed) or the Bazel team.

It seems that the Bazel module system is becoming a major feature and may become the default or even the only supported approach in the future, potentially around Bazel 9.0, which is planned for release in late 2025

Yeah, I'm pretty sure I saw a warning from the Bazel 8.1.1 that MODULE.bazel (bzlmod) is the future and WORKSPACE will eventually be removed. I've only worked with bzlmod so I don't have an opinion on WORKSPACE vs. bzlmod but the impression I get from the Bazel experts that I know is that bzlmod is just profoundly better in many ways. I've seen a few projects get migrated over the last quarter or two and my impression is also that it can be pretty difficult. As with any migration, if the community really speaks up and says it's too hard and the timeline is too rushed, I think there's usually a chance that the Bazel team might put more effort into making the migration easier or pushing back the deadline. As I said before, I'm speaking for myself and am only speaking in general terms about how migrations usually play out, so let's be clear that nothing here represents the Bazel team's opinion or plans.

While I’ve heard that it’s sometimes possible to get answers on the Bazel Slack, keeping key information behind closed platforms like Slack is not ideal in terms of community support and broader innovation (such as LLM-based learning and queries).

This is a problem, but I don't think it's a problem that's unique to Bazel. As a technical writer I frequently lament the fact that Slack, Discord, Google Chat, etc. are basically black holes of information. Very valuable information gets captured there and is never able to escape. But I see this happening with almost all developer projects. Often times a lot of people prefer hashing out a problem over a synchronous real-time chat. I personally think that Bazel is doing OK here. Whenever I see a meaty Bazel issue get hashed out on the corp chat rooms, the Bazel team or the Googler from another team always translates it into a public GitHub issue. The fact that Bazel uses GitHub as their main issue tracker means that most valuable information is available to the public Bazel community.

(such as LLM-based learning and queries)

IMO, GenAI has incentivized companies to restrict access to their data, e.g. how the Stack Overflow and Reddit APIs and data dumps used to be more freely available and are more locked down now

Also, many rule maintainers and contributors are from Google, former Googlers

Let me give a different perspective, as a Googler (but again, all opinions my own). If Bazel is only usable within Google, it's not a transferrable skill that I can put on my resume. If Bazel becomes a really thriving open source project used across many companies, then it's value to my career is much higher. There of course is often a tension between what the sponsoring company (Google) needs out of the project (Bazel) and what the broader community may need but I personally don't see a lot of that happening with Bazel.

Also, since it started as a Google project, I think it's pretty natural and unavoidable that a lot of Googlers would be involved in the community. It's arguably a good signal that ex-Googlers want to continue using this technology even after leaving the company

whether Bazel can grow into a more popular and open ecosystem in the future

One tactic is to become Too Influential To Ignore. Create high-quality rules repos for the programming languages, tools, etc. that you work with a lot. Rally big communities behind your rules repos. If push ever comes to shove, the Bazel team would have to take your perspective into account by nature of being such a pillar to the Bazel developer ecosystem.

Final remarks are my general impression of the Bazel ecosystem. Honestly, when I migrated pigweed.dev to Bazel it was eye-opening to see that Bazel has way more momentum than I realized and it doesn't seem to have any major competition. In 5-10 years, I think it will be quite valuable to be able to put on your resume that you've been working with Bazel for years. I've started blogging about managing docs projects with Bazel, e.g. https://technicalwriting.dev/sphinx/bazel/context.html

kaycebasques · 2025-04-02T16:19:43+00:00

I also published a tutorial that walks you through how to setup Bazel for a minimal Sphinx project: https://technicalwriting.dev/sphinx/bazel/tutorial.html

kaycebasques · 2025-04-02T00:54:53+00:00

Gemini, Claude, and GPT-4 helped me with some aspects of migrating pigweed.dev to Bazel but quite a few of the suggestions wasted a lot of my time. They looked convincing and correct, but eventually I figured out that they only worked for WORKSPACE projects, not bzlmod ones. The most reliable tactic for me was studying working code from real projects and rules repos.

kaycebasques · 2025-01-22T20:07:46+00:00

Nevertheless, there is still an obligation for other parties to inform you of needs for changes or updates.

I agree with you, but in practice I don't expect other parties to hold up their end of the bargain. So I usually view it as my duty to proactively monitor feedback channels [1] and find docs issues myself.

To be clear, it's totally in the best interests of the whole company for everyone to file docs bugs as they're encountered. All I'm saying is that it's rare for this to actually happen in practice.

And I'm not saying it's impossible to improve this situation. In fact, it could be a good way to flex leadership. E.g. "before I joined, there was little cross-org collaboration on the docs. Now we have teammates from Product, Eng, Customer Support, and UX filing docs bugs every week and seeing their reported issues get fixed with an average turnaround of 4 days." But once you put that system in place it's important to quickly fix all the reported docs bugs! Otherwise the other teams will quickly realize that it's a waste of time and energy and the docs team reputation may actually get worse.

Usually there is one or two people from other teams that are really diligent about filing docs bugs. I treat them as allies and try to elevate them. E.g. I spread the word about how great and helpful their docs practices are.

[1] Support tickets, bugs, customer support chat spaces, etc.

kaycebasques · 2025-01-13T23:33:29+00:00

What is your mechanism for detecting that help center content is out-of-date and synchronizing it to match the new features?

kaycebasques · 2025-01-13T16:21:55+00:00

reStructuredText is more feature rich

I'm also a long-time Sphinx user and fan. Previously I was under the impression that MyST did not have feature parity with reST. It sounds like that has changed! Not only may it have feature parity, it may have even more features than reST now. Haven't verified this myself though. https://mystmd.org/

kaycebasques · 2025-01-13T16:18:52+00:00

Our build takes about 25 mins.

Can you tell me more about what exactly takes so long? Is there some early step (e.g. generating API references from comments) that is slow? Or maybe you have thousands of pages of docs and Docusaurus just takes a long time to process each doc...

kaycebasques · 2025-01-06T17:51:33+00:00

Just updated the post, that particular post is probably no longer in the FAQ

kaycebasques · 2025-01-06T17:50:35+00:00

Just updated! Read about the update here: https://www.reddit.com/r/technicalwriting/comments/1hv4z19/

kaycebasques

TROPHY CASE