November 01, 2023
Just the other day I was lamenting the drawbacks of maintaining for Estii outside of our main monorepo.
First it was our marketing site (no-code Unicorn Platform), next it was our transactional email templates (SendGrid's visual template mangler). The last remaining hold out was Notion, which we use for our help center documentation.
The appeal of having everything in a monorepo is that everything is versioned, branched and deployed in the same way. There's a full audit trail of who changed what and when. And with GitHub you also get a place to discuss the "why" in the form of pull request discussions.
Having a bunch of content in some external database available over API introduces a lot of friction to this very elegant mental model.
An example: when we release a new feature, how does the documentation go live? With Notion we deploy the change, make sure the e2e tests are passing and then drag some docs from a preview folder to the live folder.
With content in our git repository, not only can we deploy it all together, but the tools we use for previewing changes, rollbacks, staging environments, e2e tests etc. all just works!
The one draw back (as pointed out by Dominic De Lorenzo) was that you loose the niceties of a structured, visual editing experience. Not everyone likes markdown, and setting your technical writers loose in git can be dangerous.
Fortunately, the answer to this drawback got demoed to me by Thinkmill a few days later at React Sydney. Keystatic is a very polished, visual CMS that operates on your git repository either locally, or over the GitHub API.
Very bullish on this and will be investigating how we can use it in Estii! (hint, I'm already using it on this blog)