News for hackers. Stuff that matters.
Re:What I've Learned in 45 Years in the Software Industry by rahimnathwani on Saturday December 03, 2022 @05:37PM (#33848188)
Yup, that's a good reason to keep documentation in the same repo, and to update documentation in the same commit as the code that causes the change.
Re:What I've Learned in 45 Years in the Software Industry by noisy_boy on Saturday December 03, 2022 @09:58PM (#33850123)
One scenario where I find external wikis better is when a change encompasses multiple components and you want to present an overarching view to the user + want to refer across sections. This can be managed via something like github pages for each component but the cross referring across multiple repos adds more friction. Plus to present the overall view, something like a synthetic "doc-repo" will be needed that has landing pages that connect the component-level pages. Or we can have a wiki that does the integration by refering to component level github pages but at that point why not just do the whole thing in wiki much more conveniently.

My experience is that it basically comes down to developer discipline. A disciplined developer will update the docs regardless of whether the docs are part of repo or external and vice versa.