Tom Johnson
idratherbewriting.com · Personal blog · on HN since 2007
Tom Johnson is a technical writer who covers API documentation, documentation frameworks like Diátaxis, and the effects of technology on attention.
What HN saysHN links it for documentation guidance, including his API docs course and Diátaxis overview, though one commenter says Diátaxis is not a full answer to good docs.
34HN people shared it
7linked it in comments
33stories submitted
762story points
4 months agolast shared
2007people per year2026
Most-shared posts
- 1Documenting APIs2 people · 54 points · first shared 2022 · 6 comments on HN
- 2What is Diátaxis and should you be using it with your documentation?2 people · 1 points · first shared 2024 · discussion on HN
- 3Returning to smartphones2 people · first shared 2022
- 4My awakening moment about how smartphones fragment our attention span1 people · 552 points · first shared 2022 · 221 comments on HN
- 5How to avoid being a secretary for engineers (2018)1 people · 106 points · first shared 2022 · 50 comments on HN
- 6Walking and Chatting with ChatGPT1 people · 4 points · first shared 2024 · discussion on HN
- 7The Social Web is Changing Documentation1 people · 4 points · first shared 2009 · discussion on HN
- 8Introduction to Influence on the Web1 people · 4 points · first shared 2022 · discussion on HN
- 9Do developers need code samples in API documentation?1 people · 3 points · first shared 2025 · 1 comments on HN
- 10Automate links in your release notes using AI1 people · 3 points · first shared 2024 · discussion on HN
- 11Processes for External Documentation Contributors1 people · 2 points · first shared 2020 · discussion on HN
- 12(Another) 20 usability tips for your blog1 people · 2 points · first shared 2007 · discussion on HN
- 13The problem with adopting “bleeding-edge” tools1 people · 2 points · first shared 2016 · discussion on HN
- 14Changing the AI narrative from liberation to acceleration1 people · 2 points · first shared 2025 · discussion on HN
- 15Speaking Up and Calling Out BS When You See It1 people · 2 points · first shared 2025 · 1 comments on HN
What HN people wrote when they linked it
euroderf · 2025-03-05
There's a concept called "Every Page Is Page One": https://idratherbewriting.com/trends/trends-to-follow-or-forget-every-…
An attempt to meet the needs of people following search engine links right into the middle of documentation.
This is where I wonder if an A.I. could provide missing introductory context, based on the conversation that got you to the doc.
remoquete · 2025-01-03
Diataxis gets often linked around here. It's simple, but by no means the solution to great docs. For more info, see https://idratherbewriting.com/blog/what-is-diataxis-documentation-fram…
firesteelrain · 2025-09-02
I have used MkDocs to do this in the past.
1. https://idratherbewriting.com/learnapidoc/pubapis_static_site_generato…
niutech · 2024-05-19
It reminds me of Snap (https://idratherbewriting.com/2007/01/17/preview-images-of-link-destin…
Aren't embedded <iframe>s blocked by X-Frame-Options or CSP?
devonnull · 2023-08-09
Here's a good tutorial: https://idratherbewriting.com/learnapidoc/
prashaantt · 2022-06-26
Heh, that’s exactly what he did here - https://idratherbewriting.com/blog/returning-to-smartphones/.
danso · 2018-11-01
The landing page for the announcement has a little more detail: https://www.flickr.com/lookingahead/
> Free members with more than 1,000 photos or videos uploaded to Flickr have until Tuesday, January 8, 2019, to upgrade to Pro or download content over the limit. After January 8, 2019, members over the limit will no longer be able to upload new photos to Flickr. After February 5, 2019, free accounts that contain over 1,000 photos or videos will have content actively deleted -- starting from oldest to newest date uploaded -- to meet the new limit.
I have a Pro account so maybe it's different, but I have a "Request my Flickr data" button in the bottom right of my account page: https://www.flickr.com/account
And unless something has changed recently, IIRC, Flickr had a very generous and fairly easy to use JSON API. In the past I've been able to bulk download my ~10,000 photos with just a few calls: https://idratherbewriting.com/learnapidoc/docapis_flickr_example.html