If I need to document something in a way that doesn't fit into a comment, I'll add a separate document to the source repository and then add a comment that refe

If I need to document something in a way that doesn't fit into a comment, I'll add a separate document to the source repository and then add a comment that references it in the code. If you're using something like GitHub that gives you a Web interface that renders Markdown files, the ergonomics of doing it this way are really pretty good. I feel like this is the best way to document "big picture" stuff in general. You don't want to just have the comments, because, if you carve it up into a bunch of little vignettes and scatter them around the code, it's no longer a big picture. But external documentation alone is also insufficient. If you don't mention when it's relevant, at the spots where it's relevant, then you can't rely on people to know when and where to look for it.