Define scope of gatsbyjs.org improvements

[jlengstorf]

Thanks to insights from the community and hard work by @shannonbux, @amberleyromo, @marcysutton, and others, we have a backlog of issues to address on gatsbyjs.org.

This scope is intended to define the desired outcomes and how we will measure them. From this scope, individual issues will be created so this work can be done incrementally with confidence that we're all rowing in the same direction.

What are the outcomes we want to achieve with these improvements?

This work will focus on the overall design + four critical sections of the gatsbyjs.org site.

Anything not called out in this scope will not be addressed in this project, so please review this scope carefully to make sure we didn't miss anything!

Overall desired outcomes

The following aren't page-specific, but should be true for the overall site experience.

• [code quality] Developers working on the site should have clear direction on how to use Gatsby's design tokens and common components
  • gatsbyjs.org is regularly referenced as a canonical example of implementing Gatsby. We need to ensure the code is using best practices and give developers solid examples of Gatsby patterns.
• [discovery] Community members should be able to quickly find information about the most critical workflows
  • how to get started with Gatsby (i.e. quick start, tutorial)
  • how to find answers for specific questions about Gatsby (e.g. docs)
  • how to get involved in Gatsby (i.e. contributing section)
  • how to find themes, starters, plugins, and other community-powered ecosystem projects
• [community] Visitors to the site should immediately feel the fun, welcoming personality of Gatsby and its community
  • Visitors should get a sense of Gatsby’s core values, including our commitment to accessibility and our community code of conduct
  • Visitors should see what other community members are creating (e.g. the site showcase, starters, plugins, tweets)
• [search] Users should be able to find the information they're after with robust site search
  • Site searches should include the contributing section, plugins, starters, and other site content (see Docs: reconfigure search on docs site for contributing, plugins, and starters #12503)
• [cloud] Visitors should know that Gatsby Cloud exists, understand the high-level value it provides, and know where to look for more information

Home page

1. First-time visitors should leave with a clear understanding of Gatsby’s purpose, value, and credibility
   • what is Gatsby?
   • what can Gatsby do?
   • who is using Gatsby?
2. First-time visitors should have a clear call to action to start with Gatsby

How do we measure success?

• The click-through rate to the "get started" page from the home page will increase by 5%
• UX surveys will clearly indicate that visitors understood the key information they need to know about Gatsby
  • We need to be very clear about what this information is to make sure we aren't setting ourselves up to fail — is this Gatsby's elevator pitch for what it does? what value it adds? something else?

Docs

The information architecture work from @marcysutton will inform these outcomes heavily.

1. Users should be able to easily find the information they need when navigating the docs, thanks to thoughtful organization with room to grow.
   1a. Breadcrumb and Floating Table of Contents components will help users know where they are in the docs.
2. Users with varied skill/experience levels and learning styles should get something out of the site by discovering step-by-step guidance (tutorials), bite-size recipes, and more general reference docs.
3. Users should be able to provide feedback in the moment on docs pages with the new feedback widget.

Starters

NOTE: starters require some deeper discussion about how they should evolve with themes going stable. Does the starter showcase become a themes showcase? Do they merge? Is there a separate themes showcase to build?

1. Developers are able to quickly filter and sort starters by technology, vertical, and other differentiators
2. Developers feel confident that starters are high-quality and up-to-date
3. Developers should see the creator(s) of a starter (name + avatar)
4. Developers have a clear understanding of how to use any given starter

Plugins

1. Developers should be able to search for plugins by name, tags, and README content
2. Developers should see the creator(s) of a plugin (name + avatar)
3. (stretch goal) Developers should be able to filter plugins by attributes like plugin type, Gatsby version, or goal (e.g. "styling", "SEO").

Contributing

1. Visitors should clearly understand how to get involved in Gatsby
2. Visitors should have a clear sense of our welcoming community

Next Steps

• Get docs outcomes listed by @marcysutton
• Get scope sign-off from @marcysutton
• Get scope sign-off from @shannonbux
• Get scope sign-off from @KyleAMathews
• Review with @fk to ensure everything makes sense

[jameesy]

Am so excited to see these changes.
@jlengstorf - If there is anything I can do to help then please let me know!

On a note: the "How Gatsby Works" diagram was invaluable to me when first glancing at the Gatsby site and has been an image I have referred so many people to when they have asked questions about Gatsby, GraphQL, JAMstack etc. I hope to see it still present!

[jlengstorf]

@JABedford thanks! Once we've nailed down the scope and gotten the designs, I imagine we'll have lots of small issues to implement it that we'd love to have help with!

The diagram is pretty instrumental to hitting the "clear understanding of Gatsby’s purpose, value, and credibility", so I'd be pretty surprised if we don't see something similar in the updated design.

[marcysutton]

@jlengstorf I added some docs / learning stuff to the scope!

[shannonbux]

Woot! I'm excited to approve this, just a couple questions first:

• Do we know what problems we're trying to solve and which ones are most important to solve first? Seems like @marcysutton & @prestonso's measurements of the top 25 workflows could be part of helping prioritize things
• I think the stretch goal for plugins ought to be a requirement once themes become searchable as plugins. Anyone know the timing on that?
• The plugins goals above seem easy to measure, and I totally agree with the direction of the docs and contributing goals. I just think deciding on how we'll measure them can help us know if we succeeded or not. Any ideas on how to measure whether we've succeeded at those?

Also, some relevant info about the homepage:

• Many ppl agree with @JABedford! Keep a diagram (it's ok to revise it, just as long as we have something that shows how Gatsby works). it's the most helpful thing for newcomers, according to interviews!
• the homepage is mainly a place to persuade people to get started, so keeping it focused on that goal should help simplify it. Many companies can get bogged down by trying to put everything important on the homepage. The current measure of success is how many people are clicking on Get Started.

[jlengstorf]

@shannonbux great questions!

Do we know what problems we're trying to solve and which ones are most important to solve first?

Yep!

• Home page outcomes are derived from problems surfaced by your research, @amberleyromo's thorough breakdown of Gatsby's messaging, what I've seen and heard from the community, @KyleAMathews's input, and @lindaleebumblebee's requests.
• The docs outcomes are all derived from the problems @marcysutton has been working on, including the top 25 workflows.
• Plugins and Contributing are defined after looking at feedback, strategic goals, and observing where people get stuck or confused.

I think the stretch goal for plugins ought to be a requirement once themes become searchable as plugins. Anyone know the timing on that?

Themes should be fully released soon-ish — I'd love to hit the plugins goal in this round, but we can always circle back with a new scope if necessary. I suspect we'll have an easier time doing short, fast scopes vs. trying to coordinate multiple people to slog through bigguns. 😄

Any ideas on how to measure whether we've succeeded at those?

Once we've nailed down the scope, I want to spend some time working on acceptance criteria and success metrics.

RE: this quote on the home page:

mainly a place to persuade people to get started, so keeping it focused on that goal should help simplify it. [...] The current measure of success is how many people are clicking on Get Started.

Right now the 4 outcomes above are what we're working toward, ranked by importance. Are you thinking we should eliminate other goals, or was this quote more of a general observation about home page designs?

Thanks!

[lindaleebumblebee]

Let's also keep in mind that we want a clear path to the .com site when someone shows interest in our commercial offering (such as interest in trying Gatsby Preview). Right now, most of our overall website traffic is going to .org (NOT .com) and some of our users will be interested in commercial offerings if they know about them. I see this as secondary to the main goals you've outlined above (helping developers get started with Gatsby).

[jlengstorf]

@lindaleebumblebee 💯 Raising awareness about Gatsby Cloud is specifically defined for the home page outcomes. (See outcome 4 above.)

[shannonbux]

@jlengstorf re. the homepage, I realized my concerns about the homepage may stem from just not seeing a sketch of what this project might include in the redesign. I for sure support all the goals under the homepage heading in this issue; I just don't know how to solve those things by redesigning the homepage.

3 reasons for this concern:

1. If clicking "get started" is still the CTA on homepage, and the goal is to drive traffic to that button, I wonder if first-time visitors could get overwhelmed if there are more CTA's on the homepage. Perhaps there is a way to design this to still look simple and help them stay focused, and actually persuade them even more to get started. That'd be cool.
2. People have hardly clicked on anything below the fold (e.g. the stuff added last fall just doesn't get clicked on :/) so I'd hesitate to recommend spending much engineering resources on anything below the fold when it seems like there's plenty of other work to do on docs, plugins, contributing that get visited all the time.
3. People find most things via googlesearch and site nav, so optimizing those things are higher priority than homepage

[jlengstorf]

@shannonbux I'd agree with all of that. I don't think we'll be adding any additional CTAs — we're just making sure we have the right info on the home page. Without making any decisions for @fk, I'd assume that the "community" and "Cloud" goals will be met with a combination of top nav and small sections below the fold that give a thread to tug at.

[marcysutton]

This looks good to me. I added a "1a" to the docs scope to link to the Breadcrumb and TOC component issues, so they are considered for way-finding through the docs. One of my TODOs is to scope out MDX components for docs–I can link to that from here once I've got something to review. Those seem easy enough to slot into individual pages once the overall design is figured out, while a bigger need for this scope is to make stuff easier to find. Something we hear a lot is that the sidebar is overwhelming, and people can't always find what they're looking for. Search could help out there, but it definitely feels like Gatsby has outgrown its top navigation and sidebar structure.

[KyleAMathews]

Echoing what @shannonbux said — all of the items in (2) might not best be handled on the home page. E.g. 2a is already handled very nicely by clicking "Get Started" and arriving at https://www.gatsbyjs.org/docs/

It's not clear that anything past the diagram on the homepage is particularly effective. Looking at Google Analytics, less than 1% of visitors people click on links further down the page.

I agree all the (2) outcomes are very important — just don't want to tie them unnecessarily to the homepage itself.

[KyleAMathews]

I'd also like added to this document an indication of how we'll know we're meeting the outcomes. Also what is the current state of things.

The starters page seems like it should be focused on more than plugins. Both are heavily used but the starters page is viewed more and earlier than the plugins page. And the starters page is much lower quality than the plugins page and has been iterated on less.

[KyleAMathews]

For starters some things that could be done:

it should be easier to find — highlight more our official starters, the categories should be sorted by the most common category & those be audited, same with dependencies, etc.

[KyleAMathews]

Put yet another way. These are all important outcomes but how do we know which ones currently need the most help and how will we determine whether any change we've made has reached our desired outcome?

[KyleAMathews]

I don't know that we should frame this work as "gatsbyjs.org is in need of a facelift!"

.org in general works really well. We need to identify specific incremental improvements we can make.

[calcsam]

Re: the conversation on point (2), it makes me think that the most important things to convey from the homepage -- for casual visitors who aren't planning on getting started right now but might in the future -- is the sense that there is a rich ecosystem, comprehensive documentation, and vibrant community. How much we actually share about each of these could be totally variable, the most important sense is that people get a sense of this.

To that end, I'm not sure that we want people to click the eg ecosystem links down the page, the fact that they exist helps convey the point though.

On that note, it feels like the feeling we want to convey is "you belong here" and #3 basically boils down to whether users feel that statement.

Agree with @KyleAMathews on indications of success for the homepage.

• We have an OKR goal of increasing the % of people that click on the "Get Started" button increases from 36% to 41% -- we should include that.
• Do we want to do something like UX surveys after the fact on how people feel about Gatsby and whether they're able to complete specific tasks?

[jlengstorf]

@shannonbux @KyleAMathews @calcsam I just updated the scope to do a few things:

1. Moved most of the home page outcomes to overall site outcomes — these things need to be true, but aren't necessarily page-specific. That's a good point from @KyleAMathews.
2. Added a measurement to the home page outcome since we have a clear understanding of what that should be.
   • As we nail down other outcomes, I'd like to add similar measurements for each of them.
   • It would be useful to write down exactly what we want people to know if we're going to run UX surveys as an indication of success. I added a note about this.
3. Added starters to the scope, though I think we need to discuss how the starter showcase is going to evolve with themes coming soon.
4. Improved the language in the issue to make sure this doesn't feel like a cosmetic chunk of work.

Am I missing any outcomes that we want to hit for the called out sections? Once we're in agreement I can start working toward measurements of success.

[KyleAMathews]

Like the improvements!

Thinking about this more — what you're writing is a "Product Vision" (from Inspired).

I think this sort of document needs to go on .org somewhere — and then from here we can develop our strategy for understanding how we're doing on different parts of the vision and pulling off projects to make improvements.

[jlengstorf]

@KyleAMathews in the interest of actually doing the work, does this need to move? If we can agree on what we want to accomplish, we can start putting tasks against this doc, and it's easier to reference the vision if we can tag it as an issue (or epic) from the issues that describe the work.

Does anything in this doc need to be adjusted, or can we agree that this is where we want to end up?

[marcysutton]

We've done quite a few things off of this list so far: especially for docs and the homepage. The items that are still outstanding are around starters and plugins, which will require a bigger, strategic conversation. I'm going to close this issue in favor of smaller pieces -- knowing that the starter and plugin ecosystem could use a revisit.

[gillkyle]

who is using Gatsby?

Finished with #17098

1a. Breadcrumb and Floating Table of Contents components will help users know where they are in the docs.

Finished with #15165

Users with varied skill/experience levels and learning styles should get something out of the site by discovering step-by-step guidance (tutorials), bite-size recipes, and more general reference docs.

Finished with #15251

Users should be able to provide feedback in the moment on docs pages with the new feedback widget.

Finished with #13550