[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)