[HN Gopher] The Grand Unified Theory of Documentation
       ___________________________________________________________________
        
       The Grand Unified Theory of Documentation
        
       Author : shafte
       Score  : 47 points
       Date   : 2021-04-15 18:57 UTC (4 hours ago)
        
 (HTM) web link (diataxis.fr)
 (TXT) w3m dump (diataxis.fr)
        
       | smackay wrote:
       | 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.
        
         | OkayPhysicist wrote:
         | 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.
        
         | 1MoreThing wrote:
         | 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.
        
       | somethingAlex wrote:
       | In regards to that four-quadrant infographic - how could
       | Technical Reference fall into the category of "theoretical
       | knowledge?"
       | 
       | I'd think tutorials would fall under theoretical because if it
       | gets too practical, are you not effectively writing a how to
       | guide?
       | 
       | I'm not really sure the four categories fit into that quadrant
       | scheme as well as they'd like.
        
       | formerly_proven wrote:
       | In case you went "hey, this looks like a blatant rip-off of
       | Divio's pages, doesn't it?" -- yeah it is, because this is the
       | spin-off of that particular aspect from Divio.
        
         | acemarke wrote:
         | Yeah, I _was_ sorta wondering that, actually :) I think it went
         | from being a single blog post, to its own subdomain, and now to
         | a totally different site? Kinda weird progression.
         | 
         | Love the advice overall, and I've tried to apply that as I've
         | been reworking the Redux core docs.
         | 
         | (Gotta say the new name's kinda odd, though.)
        
         | swyx wrote:
         | wait so... this is a spinoff startup? i didnt even know what
         | Divio sells..
        
       | rglover wrote:
       | Some personal rules for docs:
       | 
       | 1. Explain, in plain non-jargon words (nobody cares how smart you
       | are) what problem is being solved, how, and why.
       | 
       | 2. Provide _contextualized_ examples (no foobar), not making
       | assumptions about what the reader knows or doesn 't know (and
       | avoiding condescending language like "it's easy," "it's common
       | sense" or anything that suggests the reader is "dumb" if they
       | don't get it).
       | 
       | 3. Think in terms of a blog post/tutorial, not technical API docs
       | as a starting point. This helps with adoption because people want
       | to understand the thing _first_ and then dig into API (just
       | because you may not doesn 't mean that others are the same).
       | 
       | 4. Don't be lazy. Show respect for the people taking the time to
       | use your stuff and put in the effort (grammar, structure, quality
       | of examples, etc).
        
       ___________________________________________________________________
       (page generated 2021-04-15 23:00 UTC)