Add design notes for documenting design choices

Author: ychin

notes/Design_Notes.md

@@ -0,0 +1,13 @@
+## Comparisons
+
+vimhelp was chosen because it's modern (at least much more so than [vimdoc](https://vimdoc.sourceforge.net/)) and provides some nice features like the ability to switch light/dark modes, and presenting a table of contents sidebar. It's designed to work as as server but has an offline generation mode. We made a fork to make certain necessary changes to make offline mode generation better and to have the page actually support MacVim and have the correct information at the footer, etc.
+
+Neovim's documentation generation tool (hosted at https://neovim.io/doc/user/) was also an option and it has certain nice features, but after investigating it for a bit, it became obvious that it would be quite hard to work around the restrictions (see [this comment](https://github.com/neovim/neovim/pull/20690#issuecomment-1458796967)) due to its tree-sitter logic requiring a tighter syntax than Vim documentation currently actually uses.
+
+There were other tools like vim-jp's https://github.com/vim-jp/vimdoc-en, but vimhelp seemed to be the most used and provided the features we need.
+
+## CI
+
+Publish the documentation using GitHub pages for simplicity and so we don't have to run a server. Since everything is generated by vimhelp, we don't really need an intermediate step of pushing to a gh-pages branch first. Instead, GitHub has a newer feature that allows us to directly publish the page as an artifact and deploy from it, thus saving us from having to push to a gh-pages branch, which would actually have bogged down the repo by storing useless history.
+
+Currently it's configured to run nightly as of this writing. Ideally we have a way to check whether any change has actually happeed at the MacVim repo but that would require finding some way to store a persistent state in CI, or store a JSON file in the published page that we could query (for the last built commit). Since the whole thing finishes in like 1 minute, there really isn't a pressing need to do so.