Documentation (including code comments) are vital and important, but it's far better to bake the proper constraints into the code/specs so that it's hard to make mistakes. Then the docs are less necessary, shorter, and easier to understand. I think this is what GP is getting at.
Have you seen the oauth docs? I can’t imagine anyone having read and understood them fully, unless you dedicate your life to it.
Half of it I think is because people take "basic auth" offered by web framework, and then try to retrofit OAuth/OIDC/SSO on top of it.
If so many people are making the same mistakes, it’s your fault, not the users.
Sounds like a classic footgun to me.
If people don’t read, it’s their fault. Reading the docs is not a big ask.
Documentation (including code comments) are vital and important, but it's far better to bake the proper constraints into the code/specs so that it's hard to make mistakes. Then the docs are less necessary, shorter, and easier to understand. I think this is what GP is getting at.
Typical engineer spotted.
4 replies →
This is why login is a horrid mess. Because if it's too easy then people who don't know what they are doing set up websites.