[HN Gopher] Keeping documentation in sync with source code
       ___________________________________________________________________
        
       Keeping documentation in sync with source code
        
       Author : oguzhand95
       Score  : 18 points
       Date   : 2022-02-01 12:49 UTC (2 days ago)
        
 (HTM) web link (cerbos.dev)
 (TXT) w3m dump (cerbos.dev)
        
       | mikece wrote:
       | Why not just track the number of commits since the documentation
       | has changed as a quick way of knowing which docs are most likely
       | to be out of sync? Docs written in Markdown could have comment
       | identifying which feature they belong to; code could similarly
       | have a comment which feature they belong to. Doc pages could even
       | dynamically display the number of commits on a feature since that
       | doc page was updated... just thinking out loud here.
        
         | vegetablepotpie wrote:
         | You could gamify this by generating an update score. The more
         | often and more consistently documentation is updated relative
         | to commits, the higher the score. Nothing will be tied to the
         | score, it's just a number. It's existence would incentivize
         | developers to drive it higher. Sure you could get around it by
         | just adding a space to the .md file, but at least then you're
         | opening the file and you may see something in there that needs
         | a quick change anyways. The score would have done its job.
         | 
         | This would stop working if bonuses or compensation were tied to
         | the score. The moment that happens, people will start writing
         | hooks to update it with a space every commit, then it will be
         | ignored by devs.
        
       | rmbryan wrote:
       | Cool project and nice write-up. I wonder why you didn't use the
       | OpenDoc standard format? Were there project-specific reasons for
       | the documentation format you chose?
        
       ___________________________________________________________________
       (page generated 2022-02-03 23:00 UTC)