> A solution to this situation is shifting the focus from what should be written to what user needs should be addressed
This goes for all forms of communication, all the time. Whether you're writing or speaking or having an informal conversation, relentlessly focus on your audience: what they think, what they know, and what they need to hear.
Think hard about your audience, and then think about them again.
Oh, also my soapbox topic is all documentation should have a line at the top explaining it like you'd explain it to your parents. "This cli tool was built in order to automatically run all tests in the suite, instead of manually like before." Etc.
If you do not know your audience, think of yourself as the primary audience. There is no shame in writing as if the recipient is your (past or future) self. This has nothing to do with ego, but with clarity and self-reflection. After all, you should know yourself best.
> a line at the top explaining it like you'd explain it to your parents
Another benefit of this is that in a complex environment, this helps the user check that they have the correct manual, so they don't waste their time trying to absorb it for no good purpose, realizing only some time later that it was some other manual that they wanted.
Yes, thank you. I hate reading things like:
> The whizbanginator facilitates workflows with reductive conflapitance. Here's some info about its release cycle and on call. Here are all of its configuration details, which will make you realize it does not actually solve your problems because we never told you what it was.
Link going next to Diataxis [0] in my bookmarks.
Hi there! I'm the author of the Seven-Action Docs Model.
Big yes. I think the 7A model is fully compatible with the likes of Diataxis, or with pragmatic initiatives such as The Good Docs Project [1].
>Engineers dabbling in documentation and feeling lost as they approach the field, on the other hand, are drawn to docs frameworks because frameworks are all they’re used to working with
Im drawn to frameworks because without them I cannot implemented an automated way to address the problem of docs going out of date.
I have an issue with this because a lot of my internal documentation is drawings at various layers of detail. For whatever reason this is what works for me, and it appears to help other people on my team. But they always lag. I've tried committing svgs (useful but immediately out of date) and I'm now using mermaidjs in markdown (because github now renders these in the browser).
Do you know any framework/tool that would keep my drawings up to date? Maybe a pre-commit hook or github action that would check invariants in the code and fail to build without modifying the pictures?
That depends on what the drawings are of.
Docs frameworks (conceptual, theoretical ones) don't really solve the problem of docs going stale. Better processes and hiring tech writers do.