Comment by dont__panic | Hacker News Reader

Comment by dont__panic | Hacker News Reader

Parent Full thread

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 separate and distinct from each other.

I think tutorials and guides can live separately, but I really really struggle to disentangle reference material from how-tos. Even simple task-oriented information ("enable or disable Feature X") feels unnatural to segregate from the reference material and the explanatory info. If you do separate them, you end up with a serious linking problem, where every page is useless in isolation and users somehow have to figure out a starting point when multiple pages all build off of each other.

The best I've ever managed is a system that uses separate top-level sections for explanation/tasks/reference on a single page for a single concept. Which I suppose isn't a direct violation of Diataxis, but it feels somehow different in spirit.

How have other documentarians approached this problem?

I’m using taxonomies to tag content by topic, so if you’re on a guide or how to, you can see related references.

I’m working on documenting my knowledge as a developer and creating training material for teaching others.

Hi! Author of Diátaxis here.

Good question. And:

> This framework is helpful for thinking about content

You are absolutely right, it doesn't prescribe four boxes for all content to be forced into at all costs, it describes an approach to thinking about what you are doing when you are writing and managing documentation.

As for your question: let's say you're flying an airliner, and for whatever reason, you have to make an emergency descent. You want to know what to do. You want a how-to guide. You turn to the EMERGENCY DESCENT page in the Quick Reference Handbook. It prescribes the steps to take, in the form of a list. It says: if this, then do that. You know what you want to achieve, then handbooks guides you through the actions.

A different scenario: you're at cruising altitude, and have to shut down an engine. You want to know what the situation is (what the optimum drift-down rate is, level-off altitude, and so on) given your current weight etc. You need information (reference). You'll turn to the ENGINE INOP page, where you'll read the numbers off tables. No instructions - just facts.

In either case, encountering a mixture ("pollution") of how-to prescription in the reference description (and vice-versa) would be at best unwelcome, at worst, deadly. Your needs are different in each case. You know when you want to know what you should do, and what you should know. You know when you need to flip from one to the other. Documentation should serve those needs, by keeping the material separate.

And pilots manage even without hyperlinks, which make it so much easier for our software documentation!

Brilliant. Only on HN will get ask a question and get an answer from the author of the original document. Completely freakin' cool.

While I have you, I'd like to ask a follow-up question that's always bothered me. How do you make documentation structured this way "beginner friendly"? It seems to me like advanced users love this kind of segmentation of content, but it's tough as a new user to find relevant sections, both for getting an initial understanding and then for problem solving for specific tasks early in their user journey.

Do you have any tips for structuring documentation in such a way that you can follow the Diátaxis 4-type model while also making content discoverable? Examples would be great as well. Just tying to draw inspiration for a project I'm currently working on.

I'd say it's the other way round. If you follow the Diátaxis model, and keep thinking about your material according to its principles, you will find that the structure starts to emerge.

For an example, consider https://brachiograph.art. It's pretty imperfect documentation, but the needs of the newcomer are answered in the tutorial, along with the clear instruction: Start here. Everything else is laid out in the contents and findable there.

Reply on news.ycombinator.com