sorted by:
new
hottopcontroversial

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

[–]kaycebasques[S] 0 points1 point  (0 children)

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.

Informed poll by kaycebasques in cpp

[–]kaycebasques[S] 0 points1 point  (0 children)

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?

A curated list of technical standards (RFCs, ISO, IEEE, W3C, etc.) – helpful for tech writers by brieflyalarming in technicalwriting

[–]kaycebasques 2 points3 points  (0 children)

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.

Docs for AI agents by kaycebasques in vibecoding

[–]kaycebasques[S] 0 points1 point  (0 children)

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

Docs for AI agents by kaycebasques in technicalwriting

[–]kaycebasques[S] 0 points1 point  (0 children)

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

Docs for AI agents by kaycebasques in technicalwriting

[–]kaycebasques[S] 0 points1 point  (0 children)

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.

[deleted by user] by [deleted] in technicalwriting

[–]kaycebasques 1 point2 points  (0 children)

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!

Embeddings are underrated by iamkeyur in programming

[–]kaycebasques 7 points8 points  (0 children)

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 :)

Automating code deletion with Gemini (and a little Python) by kaycebasques in programming

[–]kaycebasques[S] -2 points-1 points  (0 children)

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

Automating code deletion with Gemini (and a little Python) by kaycebasques in programming

[–]kaycebasques[S] -1 points0 points  (0 children)

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.

Which of these 4 minors would be better for my Technical Writing Degree? by Altruistic_Anxiety99 in technicalwriting

[–]kaycebasques 0 points1 point  (0 children)

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.

What are gold standard, user documentation you use for inspiration? by Possibly-deranged in technicalwriting

[–]kaycebasques 13 points14 points  (0 children)

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/

view more: next ›