←back to thread

Focus on decisions, not tasks

(technicalwriting.dev)
293 points kaycebasques | 1 comments | 18 Oct 24 17:58 UTC | HN request time: 0s | source
Show context
javajosh ◴[19 Oct 24 14:17 UTC] No.41887889[source]▶
I am a bit confused about this advice. Who's decisions? The tool makers? Or the users?

In general, this seems like an oversimplification. It's more useful to first understand what kind of document you are writing: learning, goal-oriented, understanding, or information. [1] It would be annoying to look up the API for a function and get inundated with "decision" information, for example.

1 - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

replies(1): >>41888196 #
1. kaycebasques ◴[19 Oct 24 15:05 UTC] No.41888196[source]▶
The docs should always be addressing a user need. That does not go away. Neither does Diataxis (the four quadrants of docs that you mentioned). I think this post is striking a chord because it's unsurfacing a blind spot in the two well-known strategies you mentioned. Everyone tries to make user-focused docs and many follow Diataxis, yet we still struggle to get stuff done with docs. Starting from the foundational viewpoint of the "docs should support decisions" might be a way to make docs more useful.