[HN Gopher] The future of documentation at Canonical (2021)
       ___________________________________________________________________
        
       The future of documentation at Canonical (2021)
        
       Author : mooreds
       Score  : 26 points
       Date   : 2022-09-18 12:48 UTC (10 hours ago)
        
 (HTM) web link (ubuntu.com)
 (TXT) w3m dump (ubuntu.com)
        
       | cassepipe wrote:
       | Since it's almost one year old? Has it paid off? Was there a
       | noticeable betterment?
        
       | als0 wrote:
       | They can start by looking at the excellent documentation from
       | FreeBSD, Gentoo, and others.
        
       | jvanderbot wrote:
       | Is this why snaps don't include man pages? Because that's a damn
       | shame.
        
       | drewcoo wrote:
       | Documentation, when it exists, is usually a band-aid covering up
       | bad design. Pretty documentation seems like lipstick on a pig.
       | 
       | I would love a doc framework that was structured in a way to
       | expose that and shame bad design. "How to FOO because we couldn't
       | manage to make it easy for you" and "3 ways to work around our
       | BAR" would be wonderful help topics. Topics indexed by known
       | problem with the software. Etc.
       | 
       | Diataxis could be used that way, but is not necessarily a forcing
       | function.
       | 
       | And as far as user-friendly, I'm pretty sure users would
       | appreciate the honesty.
        
         | jvanderbot wrote:
         | This is crazy. Documentation is indicative of bad design?
         | Extensive docs, maybe. But simple docs and straightforward
         | design go hand in hand.
        
         | faeriechangling wrote:
         | Documentation is a hallmark of good design.
        
         | greendude29 wrote:
         | > Documentation, when it exists, is usually a band-aid covering
         | up bad design. Pretty documentation seems like lipstick on a
         | pig.
         | 
         | The above two ideas are incongruent, but anyway, you do realize
         | that system design can't be self-evident for complex systems?
         | How for example would you have no documentation for the Linux
         | kernel?
         | 
         | Either you're mis-communicating your point or not thinking of
         | anything larger than tiny systems.
        
       | teddyh wrote:
       | It has happened to me multiple times that I've been writing the
       | documentation for a system I've created, and found that it's hard
       | to even _describe_ how to use the system, let alone to actually
       | use it. I think " _why can't the system do all this automatically
       | for me?_ ", and I fix the system to do exactly that, and then I'm
       | relieved of the burden of having to write any documentation for
       | how to do it manually. And as a result the system is better and
       | easier to use for everyone.
        
         | MattPalmer1086 wrote:
         | Writing documentation is one of the best ways to realise that
         | you never thought much about using it :). I do this all the
         | time too.
        
         | sandruso wrote:
         | This. Everybody should try call API / functions without actual
         | implementation to see if it feels right.
        
           | teddyh wrote:
           | Note: This is a noted positive side effect of doing TDD.
        
       ___________________________________________________________________
       (page generated 2022-09-18 23:01 UTC)