We fixed our documentation with the Diátaxis framework • Hacker News Board

Re: We fixed our documentation with the Diátaxis framework

#11

Post by kaycebasques » Fri, Dec 06, 2024, 5:08 PM UTC

riffic wrote: post #9

kaycebasques wrote: post #3

What I'm about to say is a big topic that's probably better suited as a blog post, but I'll try anyways. I think Diataxis is a valuable aid for thinking about documentation strategy but is not always necessarily a literal blueprint. I.e. when determining whether you have completely documented an area, it's very valuable to ask yourself "do we have tutorial content for this area? Explanations? References? Guides?" but…

a structured approach is better than a thoughtless one. and many teams approach documentation from a very haphazard and ad hoc sort of place.

Definitely, especially since the task of "improving the docs" can feel so daunting and ambiguous.

Re: We fixed our documentation with the Diátaxis framework

#12

Post by SideburnsOfDoom » Fri, Dec 06, 2024, 5:30 PM UTC

cbsmith wrote: post #2

I always want to jump right to the explanation documentation. The rest of it seems like a waste of time (well, the Reference bit can be somewhat useful later). I find tutorials and HOWTOs as misleading at best.

Well, that's your preference, it's definitely not everyone's. But you too would benefit from the explanation documentation being clearly labelled as such, so you can go there and avoid tutorials.

Re: We fixed our documentation with the Diátaxis framework

#13

Post by cbsmith » Fri, Dec 06, 2024, 7:00 PM UTC

SideburnsOfDoom wrote: post #12

cbsmith wrote: post #2

I always want to jump right to the explanation documentation. The rest of it seems like a waste of time (well, the Reference bit can be somewhat useful later). I find tutorials and HOWTOs as misleading at best.

Well, that's your preference, it's definitely not everyone's. But you too would benefit from the explanation documentation being clearly labelled as such, so you can go there and avoid tutorials.

In hindsight, I realize my tone was off in that comment. I didn't mean it like it was the right choice or that there was anything wrong with Diátaxis. Since people find it helpful I presumed it was... and you're absolutely right about the clear labeling! This article was a really helpful insight for me.

I just hadn't really appreciated why other people wanted different kinds of documentation. I always feel like if I don't understand the "why" I really don't know the tool and therefore shouldn't use it until that was addressed.

Re: We fixed our documentation with the Diátaxis framework

#14

Post by cbsmith » Fri, Dec 06, 2024, 7:02 PM UTC

kreetx wrote: post #6

cbsmith wrote: post #2

I always want to jump right to the explanation documentation. The rest of it seems like a waste of time (well, the Reference bit can be somewhat useful later). I find tutorials and HOWTOs as misleading at best.

I guess they all have their value - e.g, imagine you just want to achieve a goal, then a turorial is exactly what you need.

If I'm in a rush to achieve a goal, using a new tool is going to slow me down, with or without a tutorial. I consequently find the tutorial of limited value and usually just something I scan through until I get to the "real" documentation. It's revelatory how this works for other people. I guess I always understood that, but didn't really "grok" it until now.

Re: We fixed our documentation with the Diátaxis framework

#15

Post by SideburnsOfDoom » Fri, Dec 06, 2024, 8:14 PM UTC

cbsmith wrote: post #13

SideburnsOfDoom wrote: post #12

Earlier quoted context omitted.

Well, that's your preference, it's definitely not everyone's. But you too would benefit from the explanation documentation being clearly labelled as such, so you can go there and avoid tutorials.

In hindsight, I realize my tone was off in that comment. I didn't mean it like it was the right choice or that there was anything wrong with Diátaxis. Since people find it helpful I presumed it was... and you're absolutely right about the clear labeling! This article was a really helpful insight for me. I just hadn't really appreciated why other people wanted different kinds of documentation. I always feel like if I…

> I always feel like if I don't understand the "why" I really don't know the tool

What I find for me, and what I think is really common, is that a longwinded "why" is not the right place to start - it's too dry, not practical, and I can bounce off it without understanding.

Starting with a demo, a "you can use this tool to do xyx in 5 lines of code, here's how" makes me see that it has value, to get a basic feel for it. And once that is in place I get that it has value - it's like a hook to hang the "explanation" on.

Then the reference is useful later, when you're somewhat familiar, but need to check a specific thing that you don't know yet. You don't need or want to read a long multi-paragraph explanation to confirm a technical "yes or no" question.

Re: We fixed our documentation with the Diátaxis framework

#16

Post by cbsmith » Fri, Dec 06, 2024, 10:41 PM UTC

SideburnsOfDoom wrote: post #15

cbsmith wrote: post #13

Earlier quoted context omitted.

In hindsight, I realize my tone was off in that comment. I didn't mean it like it was the right choice or that there was anything wrong with Diátaxis. Since people find it helpful I presumed it was... and you're absolutely right about the clear labeling! This article was a really helpful insight for me. I just hadn't really appreciated why other people wanted different kinds of documentation. I always feel like if I…

> I always feel like if I don't understand the "why" I really don't know the tool What I find for me, and what I think is really common, is that a longwinded "why" is not the right place to start - it's too dry, not practical, and I can bounce off it without understanding. Starting with a demo, a "you can use this tool to do xyx in 5 lines of code, here's how" makes me see that it has value, to get a basic feel for i…

Yeah, if I'm reading documentation to decide if there's a value proposition worth exploring, I've already made a mistake. You've got a make the value proposition, and then I'll read about the "why" to understand if that value proposition can be realized. Why would I read a tutorial or a HOWTO for something with no known value?

The reference is relevant to me too, though modern information retrieval tools make it much less so, as I can often get the reference information I want in context. The main reason the reference is helpful is that explanations often aren't as precise as you need them to be about the specifications for the tool.

In retrospect, I do get some value out of tutorials & HOWTOs, mostly as a check on my understanding. They're just not where I want to start.

I think a good way of framing it is that a lot of documentation these days starts with "getting started", and I've observed that more often than not, that actually makes everything more difficult. If I understand the tool first, I avoid going down a lot of blind alleys and misinterpretations. I have observed that people often use a tutorial or a HOWTO as a way to get something done quickly without ever reaching that understanding, but the reality is the understanding is reason you wanted a human using the tool in the first place.