Re:The Grand Unified Theory of Documentation
by OkayPhysicist on Thursday April 15, 2021 @06:33PM
(#26827008)
If 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.
Re:The Grand Unified Theory of Documentation
by 1MoreThing on Thursday April 15, 2021 @06:23PM
(#26826914)
Why 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.
Re:The Grand Unified Theory of Documentation
by benrbray on Thursday April 15, 2021 @10:02PM
(#26828531)
Sure, 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)
Re:The Grand Unified Theory of Documentation
by hrktb on Thursday April 15, 2021 @07:35PM
(#26827504)
My 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.
Re:The Grand Unified Theory of Documentation
by BiteCode_dev on Friday April 16, 2021 @01:51AM
(#26830024)
Depends 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.
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.