Google Cloud’s Kelsey Hightower knows full well what deprives software developers of their superpower.
Their coding prowess hinges on the accompanying documentation that guides users through each step of a development loop through production, according to Hightower, a distinguished engineer and principal developer advocate at the hyperscaler.
“If developers are the superheroes of the software industry, then the lack of documentation is our kryptonite,” Hightower wrote in the forward of the book, “Docs for Developers: An Engineer’s Field Guide to Technical Writing,” referring to the fictional mineral that saps Superman of his own powers.
After spotting a retweet of Hightower’s declaration, we asked him to explain his thinking in a recent interview.
“Writing code is our superpower,” Hightower said of software developers. “We can make things come to life. But when there is no documentation, you're just lost. You just have to take your cape off and go for a walk, because you just can't reverse-engineer all this stuff. Documentation is why these [programming] libraries work.”
That makes the “writer loop” just as important as the developer loop, according to Hightower. Imagine trying to write code for WebAssembly, for example, without it, he said.
“You have no idea what you can and can't do,” Hightower said. “You have no idea if it's going to support your app or not. That documentation is actually how we get our jobs done, because there's so many libraries, there's so many integration things that we have to do every day in our day jobs. If you were to take away our reference guide, we would be lost.”
To simplify the issue, Hightower likened the lack of coding documentation to a Michelin-star chef having all the ingredients to bake a cake, but no recipe.
“I just don't know what to do with them,” he said. “I don't know how much eggs I need in ratio to the flour. If you've never baked a cake before, and you don't have a recipe, it doesn't matter how good of a chef you are. You need that recipe.”
Do you think documentation is a developer's kryptonite? Or is there something else? Send Silverlinings’ editors a letter here. We may publish it.