Hacker News new | ask | show | jobs
by tstrimple 1294 days ago
Code also has the advantage of not getting out of date with what the application actually does. Invariably, documentation outside the code base often rots over time until it reaches a point it's outright misleading.
1 comments

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.
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.