2 ms·

1) Yes 2) Unfortunately solving the problem isn't as straightforward as it sounds, because notions like "intuitive" and "clear" are hard to define objectively.

1) Yes 2) Unfortunately solving the problem isn't as straightforward as it sounds, because notions like "intuitive" and "clear" are hard to define objectively. Explicitness, constraints, and simplicity are pretty objective. But intuitiveness has to be considered in relation to the current and future team (languages/idioms they're likely to have in their head, domain concepts and background knowledge they're likely to have, etc) and will always be imperfect. Of course we should still try, and as you point out, many people don't.

hinkley 6y ago
Here’s the thing. You don’t have to solve this stuff objectively. That’s a lovely long term goal but what you need right now is for the coworkers you already have to understand what a new bit of code is doing. And you can investigate that by running 1:1 usability studies. By pairing with them on using the new code. Instead of jumping in every time they get stuck, make notes while they struggle a little bit. If they still don’t get it then intervene, acknowledge this seems to be more opaque than you hoped, bail them out, then take more notes about the interaction. Maybe all you need is to switch to a synonym you mentioned in your explanation, or to homogenize argument order between some functions, or pluralize an argument as an affordance. Maybe you used jargon from a problem domain (eg, graph theory, linear algebra) and you need to think about whether you really expect everyone on the team to learn that jargon on top of everything else or maybe you should instead use terms from the requirements or application domain and leave the theoretical terms as comments in the code, or local variable names. Or maybe your whole theory of organization is inside out and backward and you need a very different API that hides or telegraphs implementation details.

hinkley 6y ago

Here’s the thing. You don’t have to solve this stuff objectively. That’s a lovely long term goal but what you need right now is for the coworkers you already have to understand what a new bit of code is doing. And you can investigate that by running 1:1 usability studies. By pairing with them on using the new code. Instead of jumping in every time they get stuck, make notes while they struggle a little bit. If they still don’t get it then intervene, acknowledge this seems to be more opaque than you hoped, bail them out, then take more notes about the interaction. Maybe all you need is to switch to a synonym you mentioned in your explanation, or to homogenize argument order between some functions, or pluralize an argument as an affordance. Maybe you used jargon from a problem domain (eg, graph theory, linear algebra) and you need to think about whether you really expect everyone on the team to learn that jargon on top of everything else or maybe you should instead use terms from the requirements or application domain and leave the theoretical terms as comments in the code, or local variable names. Or maybe your whole theory of organization is inside out and backward and you need a very different API that hides or telegraphs implementation details.