Join the discussion
Write your take first — we'll ask for email only when you're ready to publish.
- Hacker News
- I've also found these guidelines helpful:
1. In general, do whatever Wikipedia does. e.g., start with a one-sentence definition, then a couple paragraphs of summary, then go into short specified sections, and keep links to the "Citations" at the end. It's been refined for 25 years, it's older than most of your engineers, it's 50+% correct by default.
2. Keep every section to one screenful. If your reader can't see a headline, they get lost.
3. Put a funny picture at the top of the page. Or at least something off Wikimedia Commons.
4. Don't spend a lot of time writing anything. And don't use AI. The AI doesn't know what's inside your head. You yourself have an inkling. The longer you write, the further you'll get. Just write one short thing at a time and refactor aggressively later. Never throw shit over a fence blind. Nobody reads shit that's been flung over a fence.
Steven King said writing is telepathy. All mediated communication sits on a Pareto trade-off with face-to-face communication. Media is always less interactive with slower iterations. You need to figure out exactly what your audience needs, right when they're reading, and write just that, knock 'em dead, and leave. Don't add detail. They'll ask if they need detail.
- I love whenever this comes up. It’s a great framework for thinking about and writing docs.
It’s hard to keep documentation up to date, however, and I find that items like tutorials and reference materials (unless generated off versioned code) can drift pretty far over time.
A feature I like in concept that notion introduced with wikis ages ago was a “verification” timestamp, where you specify a timeframe after which the doc owner has to reconfirm that the doc is up to date. A bit too easy to rubber stamp, unfortunately, but maybe if it took the doc offline entirely without a more robust audit.
by mmargenot - I never saw the point in Diataxis, but honestly while vibe coding it's pretty convenient to tell an LLM "do diataxis" and get decent first pass documentation out of it.
- Posted many times. Here's the most recent time from 2024 (also has most discussion).by tedd4u
- We just invested a good amount of time restructuring our docs for Diátaxis. It was helpful, but I wouldn't take it as gospel. The important thing to remember is that each piece of content should be one of the four types.
If you're embarking upon a refactoring / rewriting journey for your docs, the only advice I'd share is to actually read the website beginning to end before starting. Especially this page: https://diataxis.fr/complex-hierarchies/. The guide is (unsurprisingly) very well written, and it's easy to internalize the concepts because they're repeated often.
by jamilbk - I urge people to not read this. Once you do, you will see all documentation will as the flawed and confusing mess it is. Ignorance is bliss!by Hnrobert42
- I'd like to take advantage of the attention it's getting to point out that I am working on translating Diátaxis into other languages https://diataxis.fr/translation/, and you can see an in-progress version with some partially completed translations at https://diataxis-translated.readthedocs.io/translation/.
- I and my team did a full set of documentation for handing over a codebase to the client. A large complex codebase with accumulated history and subtle reasons why things were done.
Diataxis was fantastic. It took a bit of effort to work out what the page titles were to cover everything we needed, but then when you were writing a page it was glorious.
It was so clear what you were saying and what "voice" you were writing in. If it's a Reference page you're all descriptive, with diagrams and bullet points. When it's a guide you're more discursive, but you know you're just imparting information not trying to teach. It made it so much easier to be coherent and clear about everything.
by rkangel