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. But at least we have Jira to help manage it for us.
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, 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 benefit of a community-driven knowledge platform. It more easily captures tiny chunks of knowledge. When the query 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 helps the asker, but many others along the way. And because it is community-driven, others can edit and update the information along the way.
What I am mentioning is not an Agile tool. But a core tenet of Agile is getting the right stuff done faster. In that sense, having a community platform for all the private and proprietary information not being captured consistently today can have an immediate impact. It’s docs without the pain of maintaining docs.
What you think of your current documentation practices? Are there smart methods you have used to track your technical knowledge & learning?
Why exactly do atomic bombs explode?
Okay, a bit on the morbid side, but it’s a super interesting answer…
We help IT leaders in enterprises solve the cultural challenges involved in digital transformation and move towards a community based culture that delivers innovation and customer value faster. Learn more about our work here.
