Post

One thing I’ve changed my mind on when it comes to documentation is whether to discuss implementation details. The purist in me wanted to leave them out because “the whole point is you don’t need to know!” But in hindsight this paternalises consumers. It leaves them without a good mental model.

Phil Nash

@philna.sh

I think documentation like that needs a model of progressive reveals. When you first learn how to use something, you want to see whether you can use it to achieve your use-case. As you dig deeper, it's useful to understand what's under the hood.

7/1/25, 11:13 pm0 reposts5 likes

No replies yet.