Hacker News: johnathandos

New comment by johnathandos in "Dopamine Fracking"

johnathandos — Mon, 08 Jun 2026 04:59:36 +0000

"All fixed, fast-frozen relations, with their train of ancient and venerable prejudices and opinions, are swept away, all new-formed ones become antiquated before they can ossify. All that is solid melts into air, all that is holy is profaned, and man is at last compelled to face with sober senses, his real conditions of life, and his relations with his kind."

New comment by johnathandos in "We replaced RAG with a virtual filesystem for our AI documentation assistant"

johnathandos — Fri, 03 Apr 2026 19:37:16 +0000

I think the example you give is a little backwards — a RAG system searches for relevant content before sending anything to the LLM, and includes any content retrieved this way in the generative prompt. User query -> search -> results -> user query + search results passed in same context to LLM.

New comment by johnathandos in "I Quit. The Clankers Won"

johnathandos — Wed, 01 Apr 2026 15:49:55 +0000

See one, do one, teach one.

New comment by johnathandos in "Optimizing Content for Agents"

johnathandos — Sat, 14 Mar 2026 03:31:44 +0000

Is llms.txt really useless? I've read some recent articles claiming that if you tell an agent where to find it in an HTML comment at the top of your page, the agent will do so and then have a map to all the markdown files it can download from your site. https://dacharycarey.com/2026/02/18/agent-friendly-docs/

Accountability, APIs, and the United States of Surveillance

johnathandos — Wed, 04 Feb 2026 23:22:29 +0000

Article URL: https://netapinotes.com/accountability-apis-and-the-united-states-of-surveillance/

Comments URL: https://news.ycombinator.com/item?id=46893370

Points: 2

# Comments: 0

New comment by johnathandos in "Show HN: isometric.nyc – giant isometric pixel art map of NYC"

johnathandos — Fri, 23 Jan 2026 05:47:59 +0000

Really slick. Let’s see the AI open it up so we can use it to generate a similar map for anyplace on Earth :)

Three things I think about when creating product docs

johnathandos — Wed, 31 Dec 2025 18:12:41 +0000

Article URL: https://johnathandos.com/posts/2025-12-31-three-things/

Comments URL: https://news.ycombinator.com/item?id=46446676

Points: 1

# Comments: 0

Ask HN: What would you do if you didn't work in tech?

johnathandos — Mon, 22 Dec 2025 16:15:58 +0000

This question generated some very interesting discussions in another online community I’m in. I would likely pursue a career in occupational therapy or speech-language pathology. I would love to do work that directly benefits the lives of others and to spend more time interacting with people from all walks.

Comments URL: https://news.ycombinator.com/item?id=46355364

Points: 62

# Comments: 141

How to get Pandoc to respect custom table styles in Word templates

johnathandos — Tue, 25 Nov 2025 03:33:03 +0000

Article URL: https://johnathandos.com/posts/2025-11-24-custom-tables-with-pandoc/

Comments URL: https://news.ycombinator.com/item?id=46042074

Points: 32

# Comments: 2

New comment by johnathandos in "Markdown is holding you back"

johnathandos — Sat, 22 Nov 2025 22:23:46 +0000

It’s good to spread awareness (or just remind folks) that alternatives to Markdown exist. The right tool for the job depends on your circumstances. If I were scaling a docset for a team of contributors primarily consisting of technical writers, .adoc or .rst would be my preference. If I were scaling internal docs-as-code infra for software engineers, I’d use Markdown.

Material for MkDocs is now in maintenance mode, Squidfunk announces Zensical

johnathandos — Thu, 06 Nov 2025 18:19:04 +0000

Article URL: https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/

Comments URL: https://news.ycombinator.com/item?id=45838439

Points: 2

# Comments: 0

New comment by johnathandos in "Docs like code in basic terms"

johnathandos — Thu, 08 May 2025 17:05:08 +0000

This really depends on where you first encountered the term. Anne Gentle wrote Docs Like Code, the first book I read on this topic 8 years ago. I always consider the terms "docs as code" and "docs like code" to be interchangeable, and usually use both when discussing the topic with an audience that includes a wide variety of different individuals. I think "docs as code" is probably used more in purely dev circles due to the proliferation of the "everything-as-code" construction seen in other dev-adjacent disciplines (infra-as-code, config-as-code, etc.)

New comment by johnathandos in "Focus on decisions, not tasks"

johnathandos — Sat, 19 Oct 2024 16:02:02 +0000

Thanks for sharing this post from Michelle, just shared it with some leaders at my company!

New comment by johnathandos in "Focus on decisions, not tasks"

johnathandos — Sat, 19 Oct 2024 15:14:39 +0000

You're not wrong. Business is a tough environment.

At a gut level the post seems sensible to me, and it does generate a lot of ideas about how I can make my own docs better. That's not enough, though, if I want the folks who think about docs at my org to change their approach.

As the OP states in several other comments, most writers and organizations learn to prioritize task-based documentation. If we want to adopt a better way of doing things, we need to be able to communicate why it's better. It's no different in other disciplines.

New comment by johnathandos in "Focus on decisions, not tasks"

johnathandos — Sat, 19 Oct 2024 06:29:57 +0000

Thanks for sharing. A couple of thoughts.

It seems like it's a lot harder to measure whether your docs are helping people make good decisions than it is to measure whether they are helping people successfully accomplish a task. I think we optimize for task-based/procedural docs because the business needs us to prove our value, and there is a need for this type of documentation, and there are lots of ways to measure and report on it over short timelines. But answering the question of, "Did this docset help someone build the right thing in the right way", I mean...organizations struggle to answer this question about their own products, abstracting that to try and measure the effectiveness of your docs seems super fuzzy.

Which is not to say you can't write docs that do this, just that it seems very hard to use numbers to prove that you have done so. I definitely think I could rank how well different docsets support users who need to make decisions, and I could offer up explanations to support my reasoning, but I don't know how to quantify that for the business.

I wonder how the structure of a docset that is designed to support decisions differs from that of a docset that supports tasks. I expect you'll have the same main categories (conceptual, reference, guides) but maybe a lot more conceptual docs, and more space dedicated to contextualizing the concepts. I would expect to see topics become more interdependent, more cross-references, etc.

New comment by johnathandos in "Sleep duration, chronotype, health and lifestyle factors affect cognition [pdf]"

johnathandos — Mon, 09 Sep 2024 03:11:48 +0000

Aren’t we all just offset normies?

New comment by johnathandos in "Serverless Video Transcription inspired by Cyberpunk 2077"

johnathandos — Fri, 23 Dec 2022 03:42:41 +0000

Someone is out there building and maintaining the APIs

New comment by johnathandos in "It is your responsibility to follow up (2019)"

johnathandos — Tue, 28 Jun 2022 16:34:44 +0000

To be clear, I don’t mean when you’re cold-emailing someone for an intro or a favor you don’t need. I mean when you have a dependency at work and can’t move forward without information from someone else.

New comment by johnathandos in "It is your responsibility to follow up (2019)"

johnathandos — Tue, 28 Jun 2022 14:35:29 +0000

Agree with the premise, and it can be more effective to choose a different medium for your follow-up communication. Someone not responding to email? Try sending an IM or giving them a phone call.

Documentation-Driven API Design

johnathandos — Wed, 15 Dec 2021 18:33:38 +0000

Article URL: https://medium.com/paypal-tech/using-documentation-driven-design-to-guide-api-decisions-e451d7f3e8fd

Comments URL: https://news.ycombinator.com/item?id=29569822

Points: 2

# Comments: 0