Diátaxis – A systematic approach to technical documentation authoring

As a non writer I found that even without the details there's just one very important and very basic insight here: You don't have to say everything exactly once. Until being exposed to this idea I always tied myself in knots trying to write one stream of text that serves as THE DOCS. It's impossible to do this well (once you know, it seems very obvious haha). Just realising that you can write the same info in different ways for…

Original discussion[0] on "High-documentation, low-meeting culture" from yesterday, where this was linked to by u/ebiester in one of the top comments. (also, great read) [0]: https://news.ycombinator.com/item?id=33707022

Some personal rules for docs: 1. Explain, in plain non-jargon words (nobody cares how smart you are) what problem is being solved, how, and why. 2. Provide contextualized examples (no foobar), not making assumptions about what the reader knows or doesn't know (and avoiding condescending language like "it's easy," "it's common sense" or anything that suggests the reader is "dumb" if they don't get it). 3. Think in terms of a blog post/tutorial, not technical API docs as a starting…

I'm a documentation writer at a medium-sized company. I like the Diataxis system of thinking about how-to guides vs. tutorials vs. reference vs. explanation. But I've also tried to segregate content into these discrete categories in documentation to limited success. This framework is helpful for thinking about content, but also results in a strange sidebar for your docs if you actually follow their advice: > Technical documentation should be structured explicitly around these four types, and should keep them all…