4 ms·
Doesn't the existence of blogs and Q&A sites like Stackoverflow indicate that current approaches to documentation are failing to deliver. I think there's more t
by smackay 6y ago
Doesn't the existence of blogs and Q&A sites like Stackoverflow indicate that current approaches to documentation are failing to deliver. I think there's more to the rise of cut & paste development than simply a lack of skill or a lack of time. The volume of state in some software systems is simply too great to put down in a linear document. Indeed the number of branches in state maybe too great to represent in any meaningful way or in any timeframe that's practical.
If you look at a framework like Django. The documentation is generally considered excellent. However now there is simply so much stuff that many complex things get only a cursory treatment. So everybody heads over to SO to find the question that is the closest fit to theirs.
I am not sure what would be better or indeed if there is any solution to this. The framework here layout a multidimensional approach with tutorials to get started and reference to follow up with. However creating documentation systems with that level of complexity is an enormous task and for anything of any quality, an enormous cost.
So what's the answer? I'm not sure there is one.
- 1MoreThing 6y agoWhy shouldn't the creation of knowledge and expertise come with a price tag? The question is "is it cheaper to create a system that creates new expertise than it is to hire someone with that expertise?" As long as the cost of the system is less than the cost of the generated expertise on the open market, it's a worthwhile investment.
- benrbray 6y agoSure, we could assign price tags to every human interaction and never stop. But isn't it better for everyone to build a collective wiki of knowledge that we can all share and rely on? If I spend an entire day digging through the webpack documentation to perform a certain task, I'll gladly share that knowledge freely with anyone who asks, because I think it's a complete waste of human existence for each of us individually to learn how to wrangle webpack into submission. The question becomes: If I've already put in the work, what cost is there to me to make my knowledge freely available in the form of a SO answer? Usually the answer is "not much". (I'll be sending you an invoice for this comment)
- OkayPhysicist 6y agoIf you look at certain languages, usage of such spaces is much more limited. For example, Elixir's docs are absolutely phenomenal, which leads to discussion being dominated by much harder problems than "how do I use X". The article here covers the idea pretty well. You need to cover all 4 parts of documentation, and it should definitely be all available in official documentation, rather than relying on lower-discoverablity third parties.
- hrktb 6y agoMy impression was that people went to SO to solve issues, and to documentation to think and build features. I’d see those as complementary, and don’t expect documentation to cover most questions/issues you could have.
- BiteCode_dev 6y agoDepends on the doc. If I have to do something with Django, VueJS or TailwindCSS, I always go to the doc first (mostly looking things up with "site:" in google though), because most of the time, it delivers. If I have to create a db with one owner in postgres, I will not use the postgres docs.