Top all-time · #4767
Kayce Basques
Personal blog · technicalwriting.dev · on HN as kaycebasqueswritingprogramming
Kayce Basques's personal blog at technicalwriting.dev covers writing and programming. Since 2024, 15 different Hacker News readers have linked it 58 times, most often “The intractable challenges of technical writing”. It is still writing: the last post was on 2026-10-08, and you can follow it by feed.
Too few sampled comments (3) to say how often HN recommends it.?
Why HN links it
Kayce Basques's technical writing posts on documentation practice, such as offering embeddings of docs content and reStructuredText's guaranteed-resolving internal links. Commenters engage with the ideas.
Summarised by Claude from a sample of 3 HN comments that link here. Each comment is marked recommending, critical or neutral (citing without judging); how this works.
A technical writing blog by Kayce Basques.
Most-linked posts?
- The intractable challenges of technical writing2 people · 6 mentions · first linked 2025-01-03
- A technical writer's notes on "AI that turns codebases into easy tutorials"2 people · 4 mentions · first linked 2025-04-22
- Understanding task types in the Gemini Embedding API2 people · 3 mentions · first linked 2025-05-15
- Word2vec-style vector arithmetic on docs embeddings2 people · 3 mentions · first linked 2025-10-30
- /src/link-text-automation.html2 people · 2 mentions · first linked 2024-07-31
- The Wild West of polyglot docs sites2 people · 2 mentions · first linked 2026-10-09
- Experiment: Colocating agent instructions with eng docs2 people · 2 mentions · first linked 2025-06-27
- Embeddings are underrated2 people · 2 mentions · first linked 2024-10-24
- You can deeplink to a specific PDF page2 people · 2 mentions · first linked 2024-07-11
What Hacker News says?
Tangentially related, I published some notes about "docs for agents" (e.g. `GEMINI.md`, `CLAUDE.md`, `AGENTS.md`, etc.) yesterday It's more focused on implications for docs strategy (I'm worried that agent providers are steering us towards duplicating information that's already in eng docs) rather than user best practices i.e. "put this into your agent doc to improve agent performance" https://technicalwriting.dev/a…
Comment linking /ai/agents/
on “Gemini CLI”Submitted Embeddings are underrated (2024) as a story · 484 points
HN discussionI agree that we should standardize on AGENTS.md but Gemini CLI does at least let you configure the filename: https://github.com/google-gemini/gemini-cli/blob/3a369ddec3b... Claude Code seems to require the CLAUDE.md filename. https://technicalwriting.dev/ai/agents/
Comment linking /ai/agents/
on “Gemini CLI”Submitted Embeddings are underrated as a story · 367 points
HN discussionHere's my write-up: https://technicalwriting.dev/ml/pocketflow/index.html
Comment linking /ml/pocketflow/index.html
on “Show HN: I built an AI that turns GitHub codebases into easy tutorials”Submitted Focus on decisions, not tasks as a story · 298 points
HN discussionVery cool, thanks for sharing. I imagine that this will make a lot of my fellow technical writers (even more) nervous about the future of our industry. I think the reality is more along the lines of: * Previously, it was simply infeasible for most codebases to get a decent tutorial for one reason or another. E.g. the codebase is someone's side project and they don't have the time or energy to maintain docs, let alon…
Comment linking /
on “Show HN: I built an AI that turns GitHub codebases into easy tutorials”Submitted Please support "skip to main content" on your docs site as a story · 94 points
HN discussionI've also been debating this: https://technicalwriting.dev/ai/agents/#gotta-keep-em-separa... (Quoting from that post) Arguments in favor of keeping them separated: * Writing style. In agent docs, using all caps might be an effective way to emphasize a particular instruction. In internal eng docs, this might come off rude or distracting. * Conciseness vs. completeness. In agent docs, you likely need to keep the cont…
Comment linking /ai/agents/
on “AGENTS.md – Open format for guiding coding agents”Submitted You can deeplink to a specific PDF page as a story · 89 points
HN discussion> I guess "good" technical writing no longer includes a thesis statement. Thesis is outlined in the second paragraph: > What embeddings offer to technical writers is the ability to discover connections between texts at previously impossible scales. I think it's fair, however, to say that this post is ineffective because it does not provide concrete examples of the thesis in action. My only excuse is that I never int…
Comment linking /strategy/challenges.html
on “Embeddings are underrated (2024)”Submitted Word2vec-style vector arithmetic on docs embeddings as a story · 81 points
HN discussionRealistically, it's probably the combination of both embeddings and text generation models. Embeddings are a crucial technology for making more progress on the intractable challenges of technical writing [1] but then text generation models are key for applying automated updates. [1] https://technicalwriting.dev/strategy/challenges.html
Comment linking /strategy/challenges.html
on “Embeddings are underrated (2024)”Submitted Word2Vec-style vector arithmetic on docs embeddings as a story · 41 points
HN discussion> were any direct applications to tech writers discussed in this article No, it was supposed to be a teaser post followed up by more posts and projects exploring the different applications of embeddings in technical writing (TW). But alas, life happened, and I'm now a proud new papa with a 3-month old baby :D I do have other projects and embeddings-related posts in the pipeline. Suffice to say, embeddings can help u…
Comment linking /strategy/challenges.html
on “Embeddings are underrated (2024)”Submitted Experiment: Colocating agent instructions with eng docs as a story · 22 points
HN discussionHello, I wrote this. Thank you for reading! The post was previously discussed 6 months ago: https://news.ycombinator.com/item?id=42013762 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"…
Comment linking /strategy/challenges.html
on “Embeddings are underrated (2024)”Submitted The Wild West of polyglot docs sites as a story · 15 points
HN discussion> I'm also approaching this as a technical writer, figuring out what exactly makes Kernighan's books so good. I am docs lead for https://pigweed.dev I will probably also eventually post my findings to https://technicalwriting.dev
Comment linking /
on “Brian Kernighan on “The Practice of Programming” [video]”Submitted A technical writer's notes on "AI that turns codebases into easy tutorials" as a story · 5 points
HN discussionhttps://technicalwriting.dev/data/embeddings.html#let-a-thou... > As docs site owners, I wonder if we should start freely providing embeddings for our content to anyone who wants them, via REST APIs or well-known URIs. Who knows what kinds of cool stuff our communities can build with this extra type of data about our docs? Interesting idea. You'd have to specify the exact embedding model used to generate an embeddin…
Comment linking /data/embeddings.html
on “Embeddings are underrated”Submitted You can deeplink to a specific PDF page as a story · 4 points
HN discussion> Another profoundly important consequence of this architecture: all internal links are guaranteed to always resolve (you get warnings/errors if you link somewhere that doesn't exist). I previously wrote about how baffling it is that this is not the industry standard for docs sites: https://technicalwriting.dev/src/link-text-automation.html This, so much this. It's a problem in an even more general form (for you're…
Comment linking /src/link-text-automation.html
on “I prefer rST to Markdown”Submitted Docs for AI Agents as a story · 3 points
HN discussionContext: I've been a technical writer for ~12 years. I actually started out my career migrating a startup's docs from Word to Sphinx. Then I did a lot of time on Google's proprietary CMS/platform for developer docs. Then a few years on Eleventy-based sites. For the last two years I've been back on a Sphinx-based site (pigweed.dev). I've also done some odd jobs for readme.com-based startups and have dabbled in Docusa…
Comment linking /src/link-text-automation.html
on “I prefer rST to Markdown”Submitted The intractable challenges of technical writing as a story · 3 points
HN discussionWhat's even more ironic is that it's the most profound book about technical writing that I have yet found in my 12-year career. It also inspired me to deep-dive into how the pages of my docs site relate to each other, which yielded some useful insights: https://technicalwriting.dev/data/intertwingularity.html (Baker's book led me to Too Big To Know , which in turn led me to the concept of intertwingularity)
Comment linking /data/intertwingularity.html
on “Focus on decisions, not tasks”Submitted Fine-tuning an LLM into a style guide editor as a story · 3 points
HN discussionThe post title reminds me of something that I researched a little a couple months back. Practically all embeddings are implemented as vectors, right? Definitionally, an embedding doesn't have to be a vector. But in practice there's not really any such thing as a non-vector embedding, is there? One thing I learned recently is that, if your embedding model supports task types (clustering, STS, retrieval, etc.), then t…
Comment linking /ml/embeddings/tasks/index.html
on “A visual exploration of vector embeddings”Submitted word2vec-style vector arithmetic on docs embeddings as a story · 2 points
HN discussion
