In their 2016 developer survey, StackOverflow said poor documentation is the second-biggest problem faced by developers. 34.7% of respondents reported documentation as a challenge in their daily work. It’s not clear if that is internal documentation or upstream, but in either case the pain is largely self-inflicted.
Just as not everyone can write good code, not everyone can write good documentation. It’s a skill that requires practice, experience, and some talent. But the best documentation is what gets written. Documentation often has to start with the developer, even if someone else is responsible for cleaning it up.
The developer culture must embrace documentation. Test-driven development says write the tests first and code to the tests. Documentation-driven development is similar. We can argue about which should come first, but I’d suggest the documentation should inform the writing of the tests. Essentially, the documentation is the use case: the business reason you’re going to write code in the first place.
Writing documentation isn’t fun for a lot of people, so fostering a documentation culture is not easy. You can’t just say “thou shalt document” and expect it to happen. It has to be something you actively enforce. Your pull request doesn’t include documentation? It’s not getting merged until it does. You haven’t written a word of docs all year? No raise for you.
Once documentation takes root, though, it can be self-reinforcing. In the meantime, you do your users and your future self a big favor by making the effort now.
Earlier this week, I came across a 2012 article from Poul-Henning Kamp entitled “A generation lost in the bazaar“. This is a reference to Eric S. Raymond’s seminal The Cathedral and the Bazaar, which advocates for making the sausage, so to speak, in public. Using the Linux kernel and his own fetchmail program as examples, Raymond emphasizes the benefits of rapid, iterative development and of fostering a user community that acts as co-developers. This stands in contrast to the “cathedral” style of development where a product is worked on by a small number of people until it is ready to be revealed to the public.
Kamp’s point (and subtitle) is “quality happens only when someone is responsible for it,” which I endorse wholeheartedly. However, he is mistaken to blame Raymond’s bazaar for “a clueless generation of IT ‘professionals’ who wouldn’t recognize sound IT architecture if you hit them over the head with it.” What he observes is the democratization of programming, which is due to ever-cheaper hardware, free (as in beer) software, and the Internet. Had The Cathedral and the Bazaar never been written I doubt the world would look dramatically different, at least in this respect.
IT is in its awkward teenage years. It has been around long enough that it can do pretty cool things, but not so long that it has accumulated much wisdom. The fact that anyone can write software (or copypasta snippets from various example sites and fora) and make it available to others is simultaneously a wonderful and terrible thing. Nonetheless, that doesn’t make the bazaar style wrong.
Kamp described the end result of the bazaar as “a pile of old festering hacks,” and I’ll agree that its an apt description for a lot of software. It’s probably just as apt for a lot of software developed in the cathedral style. Raymond devotes a fair portion of his book to quality and good design, and it’s unfair to blame him for people not following that part (assuming they’re even aware of his work at all).
Raymond makes many unsubstantiated claims that the bazaar style of development leads to higher-quality software. That may or may not be the case. My own view is that the bazaar style is well-suited for open source projects. After all, open source is about more than code.
One thing I’ve been focusing on lately is avoiding “It Works Well Enough” Syndrome. Maybe it’s because of the systems design classes I’m taking, or maybe it’s due to my frustration having to fix something that was done months or years ago because it no longer works well enough. Sysadmins are particularly vulnerable to this trap because we’re often not trying to develop software, we’re just trying to solve an immediate problem. Unfortunately, things change over time and underlying assumptions are no longer valid.
A relevant example from the world of tropical weather came up earlier this month. The National Hurricane Center’s 45th discussion for Hurricane Katia contained some very interesting text:
NO 96-HOUR POINT IS BEING GIVEN BECAUSE FORECAST POINTS IN THE
EASTERN HEMISPHERE BREAK A LOT OF SOFTWARE.
It makes sense that software focused on the Atlantic basin would only be concerned with western longitudes, right? It’s exceedingly rare for Atlantic tropical systems to exist east of the Prime Meridian, but apparently it’s not impossible. Whether it’s NHC or commercial software that the forecasters are concerned about is irrelevant. Clearly positive longitudes break things. It makes me wonder what broke when Tropical Storm Zeta continued into January 2006.
Sidebar — It’s not our fault/everyone else does it, too
I don’t mean to demonize sysadmins or lionize developers in the first paragraph. There are plenty of sysadmins out there who want to take the time to develop robust tools to solve their problems. Often, they just don’t have the time because too many other demands have been placed up on them. By the same token, developers who methodically design and implement software still end up with a lot of bugs.