We decided to adopt Gatsby for Sentry’s customer-facing documentation - well, I should say that I decided. We were already using it successfully for a variety of static marketing content, and I knew it had a lot of hype, so after a brief proof-of-concept it seemed like a safe choice.
To help contextualize everything I’m about to say, it’s important to understand the scope of our usage. Sentry’s documentation is not as straightforward as you might think - in fact, there are over 3,000 pages as of writing. We have a large amount of templated content designed to render language-specific examples, as well as a variety of different types of documentation (user guides, help desk-y articles, code-rich technical docs). Originally we had extended Jekyll to support a lot of this, but Ruby isn’t widely used at Sentry (approximately 0% of the engineering team knows Ruby), and it had become a big mess of spaghetti code with slow build times.
I also want to note that while this blog post is primarily focusing on the flaws of Gatsby as a framework, I’m not here to tell you that it’s not good for your use case. That said, I was not able to discover many of these short comings easily when evaluating Gatsby, and many things you read on the internet don’t stem out of real-world usage. My hope here is that Gatsby continues to improve over time, and that, as a user, you can be more informed about if it’s the right choice for you.