[HN Gopher] Making world-class docs takes effort
       ___________________________________________________________________
        
       Making world-class docs takes effort
        
       Author : todsacerdoti
       Score  : 29 points
       Date   : 2021-09-04 12:02 UTC (11 hours ago)
        
 (HTM) web link (daniel.haxx.se)
 (TXT) w3m dump (daniel.haxx.se)
        
       | kaycebasques wrote:
       | Wholeheartedly agree with the "your docs features examples"
       | principle. For code/APIs there's really two categories of
       | examples: A) minimal, viable, complete snippets that capture a
       | use case [1] and B) end-to-end working example of core use cases
       | tied together.
       | 
       | The tricky thing about A is actually figuring out the common use
       | cases and then finding the phrasing that your users would say. I
       | was lucky when I worked on the Chrome DevTools docs because I had
       | a huge record of the problems that people actually faced and how
       | they described them: all the google-chrome-devtools questions [2]
       | on Stack Overflow. For smaller products where obviously you won't
       | have an active Stack Oveflow community, a good source of insight
       | is support tickets.
       | 
       | [1] https://stackoverflow.com/help/minimal-reproducible-example
       | 
       | [2]: https://stackoverflow.com/questions/tagged/google-chrome-
       | dev...
        
       | eddieh wrote:
       | _> Your docs belong in the code repository_
       | 
       | This is essential. If developers have to hunt down the
       | documentation it will never be updated. It needs to be generated
       | from plain text files in the _same_ repository.
       | 
       | Way to many times have I encountered documentation fragmented and
       | outdated split between Confluence, Google Docs, Google Sites,
       | GitHub wikis, network shares, Dropbox, Google Drive, separate git
       | repositories, and other such abominations (MS SharePoint).
       | 
       | Treat you docs like code, treat it like it's important, it is the
       | least you can do to even have a chance of producing marginally
       | acceptable documentation, let alone good documentation.
        
       | z3t4 wrote:
       | Documentation is underrated. If the documentation is bad I know
       | it will cost 3x or more to implement. Most of the time I do look
       | at the source code, aka "the source code is the documentation",
       | but if the "source code" is 10000 modules with glue code, and
       | there is no documentation - I will not even bother.
        
       | mukundesh wrote:
       | I hate viewing documentation in a browser, too many distractions.
       | Everyone should distribute docs in a dockset format
       | (https://kapeli.com/docsets).
        
         | nzmsv wrote:
         | Huh, looks like a modern-day WinHelp. That looks like it's
         | moving in the wrong direction though. I doubt many people want
         | a big completely offline doc blob in this day and age.
        
           | mdaniel wrote:
           | In my experience, local copies load appreciably faster and
           | more consistently than CDN-ed, Google Analytics-ed hosted
           | copies
           | 
           | I'm beyond livid that Firefox Developer Edition stopped
           | allowing me to paste "jar:" protocol URLs even though it
           | still loads the existing ones I bookmarked just fine
        
           | eddieh wrote:
           | Actually, I wish more projects had installable documentation.
           | Obviously, I don't want WinHelp, but man pages, HTML, and
           | PDFs easily installed to a discoverable place, yes please.
        
       ___________________________________________________________________
       (page generated 2021-09-04 23:02 UTC)