Markdown-in-git used to be used for tech specs at my company. Now we switched to Google Docs, which means we need to maintain a "change log" section at the bottom because Docs history is... not a commit log.
Markdown in git, reviewed as a pull request on GitHub, is the best way to do an RFC. I will die on this hill.
Alternatively, I wonder if an old school message board would work. Each RFC gets its own (sub)board, and within that board each thread is a discussion about some topic -- an individual review, debate about a section, etc. I wonder if such a thing already exists, _specifically_ for technical specification review.
1. Some devs just didn't like having review discussions as PR comments. Maybe it's the way that the threads break up the markdown source. Or maybe WYSIWYG feels better for doc review. I also recall people saying "it's hard to know what's changed, could you add a changelog section?" When I replied "it's a git repo, and I leave detailed commit messages," there was no response. I think this means that they don't like that.
2. The managers who decide things don't use git. We use Google Docs for everything else, why not for this?
In the end, Google Docs works well enough. I do miss the commit log, though. It's tricky to link to a previous revision in the changelog table -- maybe I'll get into the habit of it.
Both GitHub PRs and Google Docs have this problem, though: There's no ready record of the review process -- the comments. They eventually disappear and are difficult or impossible to retrieve, and they lose context.
Markdown in git, reviewed as a pull request on GitHub, is the best way to do an RFC. I will die on this hill.
Alternatively, I wonder if an old school message board would work. Each RFC gets its own (sub)board, and within that board each thread is a discussion about some topic -- an individual review, debate about a section, etc. I wonder if such a thing already exists, _specifically_ for technical specification review.