Writing developer documentation is a great way to show your coworkers that you care about them. Where should you put it though?

There are a few choices:

• wiki software like Confluence from Atlassian
• Google Docs
• hackmd.io
• checked into source control

I think the last one is usually the right option. Here's why:

1. You can find the documentation using the same codesearch tool you use for code.
2. The documentation is versioned along with the code, so you can see what it looked like for last month's release.
3. You can ask for documentation updates in the code review and ensure they're added atomically along with related code changes.
4. Code reviewers can help make docs correct and readable while the content is still fresh in your mind.
5. The documentation can be executable, by adding a test next to it that extracts some content and runs it.
6. Code generator tools in the repo can produce documentation. For example, your API schema can be included in the docs along with prose.
7. All the familiar tooling for diffing, bisecting, and blaming are available.
8. Your CODEOWNERS setup is re-used to ensure docs are reviewed by the right team.

HOWEVER there are downsides to documentation-in-code, so you should be sure to mitigate these in your environment:

1. Make the presentation pretty. A README.md in GitHub is rendered okay, but it appears below the source code listing for the folder. Something like GitHub Pages is a pretty easy way to show it. To be fancier, you could use a static rendering like gohugo.io as a post-commit hook on CI.
2. Make sure the "pencil" icon is enabled in your source browser. It should be as easy to suggest changes as it would be for a wiki, or else the "activation energy" is too high and engineers will tend to avoid the context switching required to make changes.
3. Update your code review approval requirements so that pure docs changes are not difficult to land. For example you might skip testing and allow commits with no review at all, if you want a true "wiki" experience.

Note that there is a case where docs shouldn't go in version control: when non-engineers need convenient edit access as well. It's not fair to make someone learn git and Markdown to edit non-technical documentation.