Yesterday, I posted some thoughts on the announcement of closing down the StackOverflow Documentation Beta. I tweeted the first question I had after seeing this announcement:
“we know a lot more about what makes for great documentation…” I wonder if they asked anyone first? https://t.co/FniAbex3ts
— Bob Watson, PhD (@bobwatsonphd) August 2, 2017
And got a very gracious reply from Jon Ericson, the community manager who posted the announcement. I was impressed and, after reading some of Jon’s other posts related to this announcement, developed the utmost respect and admiration for his candid and open discussion of the project. That takes integrity and dedication at a level to which I can only hope to aspire. I’m feeling a little jealous, but in a motivational way.
Thanks to the transparency of the posts about the project, there is a lot for developers and technical writers to learn, here.
Starting with the kick off (which was not written by Jon).
I’m a late comer and still getting caught up, but Jon replied that they did do some research. In Tearing Down the Structure of Documentation, he refers to research in the Warlords of Documentation: A Proposed Expansion of Stack Overflow post, which seems to have been a kick-off of sorts but two sentences from that post hit close to home and demonstrated some serious developer hubris:
- Documentation in 2015 is something every developer needs regularly, and something that by most appearances stopped improving in 1996. We think, together, we can make it a lot better.
- Documentation is often an afterthought, obviously done just to say that it exists, with little concern for its quality. We’ve all seen plenty of this in our time.
Beth Aitman (@baitman) characterized this best by tweeting this xkcd comic:
I get that you want to rally the troops, but you lost all the tech writers with the first point before you even got to the list of the problems you wanted to solve—leaving exactly whom to fix them? This strikes me as saying the best people to fix turbulence are the passengers who complain about it. I hope v2.0 starts off with a little more empathy.
I and many others have studied this from many directions (here are just the articles I’ve written on the topic) so, if you have any questions about the topic, feel free to reach out to any of us.
The Sunsetting Documentation post describes (perhaps without realizing the irony) the very problem that leads to the kind of documentation they were complaining about in the Warlords post, by saying, “While we have an exceptional team of engineers, there just aren’t enough of them to support all the projects Stack Overflow is working on. … In order to hire more people, we need to make more money.” Something that every tech writer has heard in the months ( or years) that precede the release of exactly the documentation described in the Warlords post.
If it was easy (or cheap) to “fix” documentation, it would have been fixed, already.
I’m sorry to hear that the project didn’t turn out as hoped. It happens to the best of us and it’s never fun. It sounds like the team will go back to learn from the experience, so I’m looking forward to v2.0. As a tech writer and academic, I’m always interested in ways to improve the documentation experience.
We all need to work together, after all we have the same goal.