Cloud network architects are really smart hoomans. Here's a selection of the letters they are writing to us.
Want to write your own letter, or send us a tip? Just click here.
Documentation as the software developers' kryptonite
Re: "Google Cloud’s Kelsey Hightower reveals software developers’ ‘kryptonite’," by Donna Goodison, Jan. 5, 2023
To the Editors:
There are so many ways to take that title, but Kelsey's comments are spot on as usual. However, there are many colors of kryptonite that all do different things to the Man of Steel, and there are similar nuances to "documentation" issues and their impacts on software development.
Lack of documentation (period) can absolutely be a death sentence for a development project. It can be even worse for a maintenance or re-development project, but incorrect, incomplete, or misleading documentation can result in anything from paper cuts to a persistent, vegetative state.
I've met a few agilists who were virulently anti-documentation (or artifacts in general). I'm not sure how that plays out for them in anything longer than a few sprints, but there are a lot of folks in the IT field who hate writing anything but code. Even comments are anathema to some, so are they factories, creating some color of kryptonite?
This is one of the places where an actual computer-aided software engineering (CASE) tool differentiates itself from a mere software development kit (SDK) or integrated development environment (IDE). Turning the software itself into documentation that's meaningful can be a big win. Which/whether any particular tool does that well is an open question, especially with the rise of AI coding helpers trained on other people's (suspect?) code.
The highest functioning, fastest moving, and most successful team I was ever a part of included an embedded documentation specialist/technical writer. She made us more successful in every possible way, and when she asked a question in a meeting, we all knew it was time to stop and answer, since we had left out something important. The impact of that kind of talent cannot be overstated.
Do we absolutely need it? Yes! Do we often hate to write it? Yes! Do we always keep it up to date? No! Do we need human and robotic help? Yes!
My $0.02 worth (adjusted for inflation)...
Christopher Petersen, Crystallized Software
Collinsville, IL
Got something to tell us? Good? Bad? Ugly? We may just publish it. Write to us here.