Question: I’m tasked with making a set of developer docs more user-friendly so that people will adopt our open-source framework, but the core developers don’t see why being able to find things in the docs is such a big deal. Maybe they think everyone should just read the code.

Answer:

Remember the old movie “Ninotchka” with Greta Garbo? She’s a Soviet agent during the Cold War, back when Russia was Communist and was called the U.S.S.R. and was considered bad. Melvyn Douglas is a charmingly detestable capitalist who wins her over, eventually.

Before he does, though, she’s talking about mass trials, purges essentially. She says, “There will be fewer but better Russians.”

I think that’s what’s going on with the developers. Even if you possess the charm of a thousand Hollywood actors, you probably can’t win them over. If they don’t see the need to help newbies learn their technology, or find needed how-to topics in the documentation, there’s not a lot you can do about it.

From what I hear, bad developer docs are the norm, meaning, nobody knows anything different. Any developer smart enough to design a new framework, a new library, or a new language, isn’t going to rely on docs. The rest of us do, but if those developers were thinking about us, they would have no time to code. Plus they’d waste valuable brain cells on empathy and caring, which are inherently un-measurable and therefore, valueless.