This is such a great story and an important one. I always optimise examples for people copying and pasting, trying to make it as safe and meaningful by default as possible. It doesn't matter why you're copying and pasting - you may not have a lot of skills in this specific area, or you might be in a hurry. If you know what you're doing, you can probably improve the code, but if you use it as-is, it shouldn't come back to bite you!
Over a thousand posts (I've been doing this a while apparently) on APIs, open source, backend scripting languages, developer experience/relations, other random tech, and the occasional recipe.
This article picks up some good points, but it seems like the main criticism is that Diataxis isn't useful for a programming language because that requires a sequence of lessons. But docs aren't a textbook, if you want to create a learning resource that's great - but that's not documentation IMO.
The textbook aspect of programming languages really is the key idea here IMO. There is something in the textbook example that doesn't seem to line up well with Diataxis's 4 modes of documentation. And IMO it totally does fall under documentation. If writing something like the Rust book is the difference between your project succeeding and failing, then that's the type of doc you've got to focus on. You can't not do the work just because it doesn't line up with some theory of doc types.
Happy to see someone beat me to the recommendation of longreads.com, I get their weekly newsletter and have found some really great pieces there that I wouldn't have seen otherwise.
There’s no such thing as “pretty diagrams”, lornajane. I believe you simply has boarder interests in life which inherently make inter-links less realistic.
This is a really good point, I am using Obsidian but I feel OK about the proprietary-ness of it because at the end of the day, it's a nice tool to read my well-organised folder of markup files with. It's possible I live to regret this ...
I'm a big fan of https://codeascraft.com/ which unashamedly long form writing about interesting technical problem solving. The authors do have their own voices but it's all at a really good standard.
Do you have some tips on doing good writings? It's something I'd like to improve on but I haven't seen it done really well so far. If you have any recommended resources for learning more, I would be interested to dig in.
(unless the reason you're giving AI the code is that you don't have any docs for either humans or machines)