IMHO: don’t write documentation that leaks internal design details. Your developers may enjoy the textual reminders, but that is not what your “users” want to know when they read your docs.
I think it depends on the domain. For anything stateful, I care quite a lot what persistent data structures or replication algorithms are being employed, otherwise I have no idea how useful it will be to me. Anything computationally intensive, I need to know what the general work distribution strategy will be otherwise I will use it incredibly inefficiently. For stateless low-scale webapps, it doesn’t matter, and more information just slows me down.
What does he mean “Documentation is for users”?
IMHO: don’t write documentation that leaks internal design details. Your developers may enjoy the textual reminders, but that is not what your “users” want to know when they read your docs.
I think it depends on the domain. For anything stateful, I care quite a lot what persistent data structures or replication algorithms are being employed, otherwise I have no idea how useful it will be to me. Anything computationally intensive, I need to know what the general work distribution strategy will be otherwise I will use it incredibly inefficiently. For stateless low-scale webapps, it doesn’t matter, and more information just slows me down.