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.

I think the problem with discussing implementation details in documentation is that you risk people relying on those implementation details in weird ways. I’d still like to see more of it, but I also understand there’s a trade off.

Like a “this may seem a bit weird, but here’s why we did it” would be cool in a lot of places

Consumers relying on implementation details is part of why I liked to keep them hidden. I don’t think it’s worth the trade off though. Knowing implementation details gives you more confidence to build on top, lets you better understand what’s possible, and gives you more context when debugging.