If you’re a Gatsby community member, you may have noticed something: we write a lot.
Community members are often surprised by the comprehensiveness of our documentation. We publish new articles on this blog multiple times per week, from both the core team and the community.
Writing isn’t something we just do because we love it (although we do). Writing is core to who we are as a project, a company, and a community.
Writing is core to the success we’ve enjoyed so far, and it’s core to our strategy to become the default way to build on the web.
Principle 1: We write
Some Inkteam members who have been regularly writing (speaking, appearing on podcasts, streaming): Jason, Marcy, Amberley, Linda, Dustin, Shannon, Jim, Marisa, Preston, Mikhail, Sid, Andrew, Mike, John, me, and
Kyle,
And it’s not just the Inkteam. The documentation, while curated by the Inkteam, has largely been authored by enthusiastic community members, along with about half of our blog posts.
Off this blog, on Twitter and the wider web, every day brings four or five community members writing about their experience.
Why do we write so much?
The answer:
Principle 2: content acts as a guide unlocking the power of Gatsby.
Gatsby is so powerful, because of its core and the ecosystem — not just plugins and themes, but React, webpack and Babel, the entire npm ecosystem, and modern JavaScript in general.
You can do almost anything you want with Gatsby, you just have to:
- know why & that it’s possible
- know how to do it
Roughly speaking, there are two sides of content at Gatsby — marketing content which focuses on (1), and learning content which focuses on (2).
An example of (1) might be Linda’s How To Talk About Gatsby To Your Clients and Team.
An example of (2) might be Jason’s Learn With Jason series or really anything in the docs.
There’s tons of overlap – why points to how, and how points to why. You could argue we’ve spent more time on (2) than (1), but the reality is that we’ve only scratched the surface of what’s possible.
Principle 3: because Gatsby is so powerful, the ground to cover with writing is huge, yet essential
- Marcy’s Q2 2019 project is to catalogue the Top 25 Workflows people do with Gatsby and improve the experience for 5-10 of them. You’ll notice that many of them are not exclusive to Gatsby, instead they’re “what you need to do in order to build a website”.
- We identified about 50 key messages relating Gatsby to high-level benefits (such as improving security, reducing cost, simplifying your stack), to different technologies (WordPress, Drupal), vendors (Contentful, AWS), and communities(JAMStack, modern development, accessibility). In addition, they cover messages that are important for the wide range of personas in the Gatsby ecosystem — marketers, educators, open-source contributors, plugin authors, numerous flavors of developers, etc.
Each of these 70-80 messages & workflows probably has ~10 sub-workflows/sub-messages/features — imagine for each of these we had 3-5 case studies, docs pages, dedicated tutorials, starters/themes with annotated open-source source code — that’s thousands, probably tens of thousands, of pieces of content. That’s why we’ve only scratched the surface of what’s possible.
Our ideal version of Gatsby is a hyperconnected city — connected to all of these somewhat disparate communities (WordPress, Drupal, modern frontend, accessibility), and so on.
People from each of the communities who have discovered Gatsby are the experts on delivering the message of “why Gatsby” to that community.
Our objective is covering the ground — or if you prefer, breadth-first search rather than depth-first search — making sure that each meaningful message has at least some basic material (both documentation of how and the why of case studies and success stories).
In our content database, which lives in Airtable, we store an auto-updating column in the Messages table, which tracks the number of content pieces per message.
But…there’s a lot of ground to cover? Yes, there is.
It’s essential to our mission, though, because in order to become the default choice for building on the web, people need to realize that Gatsby can do anything you conceivably want – this is why WordPress became 30% of the internet! – and we emphasize that by writing about all use cases.
“Gatsby can’t do X” gets rebutted by “Here’s a case study of Gatsby doing X”.
(For more background on this concept, read about “economies of scope” or think about companies that have flourished by providing access to literally everything their customers needed — the 1897 Sears Roebuck catalogue had around 73K items; today, Amazon (the “Everything Store”) has 100s of millions of items.)
The challenge, is of course how do we write all of that content?
Principle 4: Leverage ourselves through collaboration.
Some examples:
- We strive to appear on podcasts, because of the huge reward / time effort, as well as because podcasts build on an existing community/listener base.
- We encouraging the community to give conference talks, write on their own blogs, and on the Gatsby blog. Individuals can establish themselves publicly as talented developers and Gatsby experts, while companies using Gatsby can publicly showcase their efforts for both internal and recruiting benefit.
- Jason’s livestreams are fundamentally collaborative — inviting one person who is an expert in a different technology for cross-pollination.
- We maintain close relationships with educators who create comprehensive, complementary content, and provide encouragement to first-time users that you can do this!.
If you’re doing interesting, innovative things with Gatsby, especially in a professional context, we’d love you to write blog posts, tutorials, and documentation about what you’re doing!
Principle 5: Content is not just individual pieces of work, it’s compilations.
If content were music, it wouldn’t consist of just “songs” — it would also include “playlists”, “albums”, “discographies”, “soundtracks”, and “multi-box sets”.
On the one hand, there is so much left to write. On the other hand, because we’ve already been writing so much for so long, we have SO MUCH CONTENT that a key challenge becomes organizing that content in useful ways that provide comprehensive treatments of particular topics.
In the docs, things are structured hierarchically, so usually content is mostly adjacent to related content on the left sidebar.
But outside the docs, that’s far from the case. We have blog posts, using-* example sites / guides, starters, conference talks, podcast appearances, tweets, and whatever Gatsby community members dream up and publish!
It’s a constant challenge to organize these in ways that are useful and obvious for the end user. We’re always attacking this in five or ten different ways — discoverability via search, cross-linking, hierarchy, navbars and breadcrumbs, turning conference talks into blog posts and blog posts into docs.
Our goal is to make it easy for the user to gather relevant context, know where to look when they get stuck, and feel confident that they can make it if they keep on reading, learning, and trying.
Principle 6: make it easy for folks to become engrossed with Gatsby
Building sites with Gatsby is the way of the future. Our goal is to let people dive as far deep into it as they want, and encourage them by providing them more and more to discover.
We want everyone to build and keep building, read and keep reading.
We want everyone to understand the depths of Gatsby, to hunger and thirst for knowledge, to tell all of their friends and coworkers and significant other all the cool things they are learning and doing with Gatsby until those folks check it out too.
We want folks who build their site with Gatsby; to build a plugin. We want folks who write documentation; to want to contribute code.
We want folks who contribute code to dive deep into Gatsby’s core, to the internal plugins where few other than Michał and Kyle dare to venture.
We want to do this because Gatsby is the future of the web, a place where performance and accessibility don’t have to be reinvented site-by-site but can come baked in, where you can author your content wherever and still have an amazing developer experience.
And we want everyone to know about it.