Mo’ Docs, Mo’ Problems
We are in an era where more is better. Or is it? One study on the nature of choice turned that assumption on its head. With more choice came increased “anxiety, regret, higher expectations, and self-blame”.

The more is better philosophy also runs into issues elsewhere. Take fitness. I was training for a marathon last year, got ahead of myself, and ended up with some painful ankle injuries. Whether sports, food, entertainment, fame, or money, maybe Biggie was right?
Some time back I talked about how we sometimes mistake “make work” for “doing work”. The cause is the myriad of tools and processes that merely move work around. We are faced with more, yet seem to be getting less out of the equation.

This of course flies in the face of the Agile Manifesto. It tells us to prioritize people and interactions over all of this added stuff that gets in the way of real work. The second line of the Manifesto extends that idea:
“Working software over comprehensive documentation”
Documentation is definitely in the “make work” category. If you had to decide between bug free and functioning software or a nicely formatted and structured set of documentation, is it really a hard choice?
Of course, that is not the reality we live in. We need both software that works and instructions to help users, support staff, and other developers know how the software works. How do you strike a fair balance?
Let’s state the obvious, no one likes writing documentation, especially programmers. As one person quipped, documentation is like the “castor oil of programming”. Furthermore, it is a pain to update and correct, it is not interactive, and it is not structured in such a way to help troubleshoot issues.
When people have questions, they want the fastest way to the right answer. Could that be documentation? In simple use cases, certainly. But when it comes to more complex technical matters, docs are often either too high-level or too far in the weeds. We need the “Goldilocks” of documentation.
That is the enormous benefit of a community-driven Q&A format. It is an atomic unit of knowledge. When the question is well structured, it is specific, relatable, and bite-sized enough for others to understand. This leads to specific, objective, and verifiable answers that not only help the asker, but many others along the way. And because it is community-driven, others can edit and update the information along the way.
We do not talk about Stack Overflow as an Agile tool. But core to Agile is getting the right stuff done faster. In that sense, having Stack Overflow for all the private and proprietary information not being captured consistently today can have an immediate impact. It is docs without the friction of spending time or resources.
Thanks for reading and let me know what you think of your documentation practices, the good, the bad, and the ugly.

Why exactly do atomic bombs explode?
Okay, a bit on the morbid side, but it’s a super interesting answer…
I help senior IT leaders and companies solve the challenges involved in digital transformation and moving towards a developer-centric culture that delivers innovation and customer value. In my day job, you can find me here.
