Tim Post


Why Improving Documentation Means Improving Engineering Culture

Tim Post's photo
Tim Post
·Jun 24, 2021·

4 min read

Understanding and improving the ways that we, as programmers and developers, learn from each-other has been something I've been passionate about since I first discovered Usenet. My experience with asking more experienced programmers for help until that point had not been very pleasant; I was frequently and openly admonished in the computer lab in college for, well, being a n00b. I had to bribe the really smart programmers with fireworks and other contraband to earn a few minutes of their time. That was just how it worked in the late 1980s and early 1990s: you hit the books, or bribed someone smarter than you.

Prior to The Eternal September, I used Usenet under various university pseudonyms to ask a lot of questions, and received answers that were of better quality and depth than I could have gotten from my instructors. I wasn't moving the turtle in LOGO, I was learning assembly by looking at intermediate compiler output from C code and that, well, just wasn't in the syllabus. What resonated the most with me aside from Assembly being extremely difficult to learn was that people were taking more interest and ownership of what I was asking about than I had in it myself -- and I had quite a bit. I kicked off a chain reaction where asking for knowledge resulted in more questions, and more people collaboratively exploring them. I realized that I just created a tiny community of people with an inordinate level of interest in intermediate compiler output and understanding optimizations, and had just witnessed a tiny formation of critical mass.

I found the same sense of exhilaration when I first encountered Stack Overflow, back in 2008 during the tail end of a pretty wild private beta. Like everyone else, I was sick of paywalls, and equally sick of clicking through 30 pages of "I'm having this problem too, any updates?" just to find an answer that didn't help. "This." I though, as I was looking at how the system worked. "This is the great days of Usenet, minus the spam, and you can edit stuff after you post it." I said that out loud, and that really was it for me - I was hooked. We all know what happened then, well, at least I should, because I spent 8 years working there subsequently. I'm still a moderator, to this day!

One of the things that I'm most proud of at Stack Overflow is something that's not even really mentioned much, because it happened so gradually. Initially (circa 2010 - 2014) we would receive constant flags from university professors that demanded information about users that were obviously using the site to get help with their assignments. They weren't the only ones noticing the uptick in odd questions, people in the community were concerned about it as well. We, as the moderators led the community to accept questions involving silly constraints just like any other question, and soon university professors began reaching out to us to ask about how students could or should be using tools like Stack Overflow in their curriculum. Over the course of the next few years, use of the site by software engineering students became almost as accepted as advanced math students using calculators. I'm just incredibly proud and privileged to have played a part in that.

So, these days, we're great at being generous with knowledge. We also now collectively empower one another to dictate the ways that we learn through change and practice. That is a huge leap that Usenet me never thought he'd see in this lifetime, but we have more work to do before we have truly efficient paths to-and-from being a code contributor to anything. We need to develop the "documentarian" part of our culture so that we're obsessive about capturing everything we know about a project, so that everyone wanting to join it has a level playing field.

We need to constantly assess, and check, our instinct to be gatekeepers at every intersection where rules start to look like gatekeeping, and we positively must make knowledge as deliberate and continuous as our code . I'm excited about this part of the journey (disclaimer, I work for the company mentioned in that link), and amazed at the transformations that I've witnessed. News of Stack Overflow being acquired really prompted me to think back on some of the key parts of how our industry arrived where it has. And if you got this far, thank you for reading, and I hope you got something valuable out of it.

Until next time!

Share this