Tweaking tutorial structure

[shannonbux]

Description

Here's a list of feedback from UX research (interviews) along with --> possible solutions. Looking for feedback/ideas/reactions!

• [x] Beginners to programming need an intro to basic tools --> Create tutorial Part Zero
• [ ] The getting started/docs/tutorial divisions can confuse people on first visit to website --> Edit tutorial landing page to mimic the flow of onboarding like Django tutorials by presenting all choices at the beginning
• [ ] Installing new starters for every part of tutorial feels like a distraction to some beginners --> Use one starter instead of new starters for each part of the tutorial (would need to introduce a way for people who want to start later in the tutorials to join--a way to clone the project they would have built had they gone through all previous tutorials). Previous issue on this: #3956
• [x] "Part 1" is not descriptive if someone wants to preview or remember what was covered --> Create descriptive titles for each part of the tutorial (carry over to URL)
• [x] Almost everyone is new to GraphQL and gets overwhelmed by Part 4 --> Break GraphQL tutorial into parts: Querying for data in your first Gatsby site (Part 4), Source plugins and transformer plugins (Part 5), Programmatically creating pages from data (Part 6), Rendering your queried data in style (Part 7)

Files to be changed (those with bullet points could be created soon, and will be updated as links soon)

/www/src/pages/tutorial.js

• docs/tutorial/part-zero

/docs/tutorial/part-one/ /docs/tutorial/part-two/ /docs/tutorial/part-three/ /docs/tutorial/part-four/

• docs/tutorial/part-five
• docs/tutorial/part-six
• docs/tutorial/part-seven

@davidluhr, @benjaminhoffman, @amberleyromo and many others who might be interested

[benjaminhoffman]

+1 on breaking out the GraphQL into two posts. I found it straight forward enough to get started but got stuck on a few parts when I branched off to my own use case.

[jlengstorf]

@shannonbux Looks great! Let me know if I can help.

[amberleyromo]

I may be misunderstanding the "files to be changed" section, (if so, ignore the following graf) but it seems like in the spirit of the fourth feedback piece (about descriptive titles for each piece of the tutorial) it may be helpful to carry over that descriptiveness into the URL for the tutorial (rather than /docs/tutorial/part-one/). Adds flexibility to reorder as well, if the need arises.

I've not used Django, but I clicked through and definitely see the appeal of the way they've organized that page. Feels clear, inviting.

[shannonbux]

Question: What do ya'll think is the best way for learners to trouble-shoot stuff and get help? Is Discord or Stack Overflow the ways to go, or is there something else better we could do?

[shannonbux]

Also, wondering if it would be cool to have a way for people to share the site they built. Like at the end we could encourage them to tweet it with a special hashtag, or is there a better way?

[KyleAMathews]

Discord + Stack Overflow + Github issues

@shannonbux oh yeah! Encouraging people to tweet about their new site would be awesome. Lots of people already do but this would probably get more.

[amberleyromo]

+1 discord for community learning. Also probably a good way to divert user questions from GH Issues that are more learning/usage oriented than actual bugs or issues.

+1 hashtag is probably the best way -- a dedicated hashtag for gatsby projects outside of tagging the general @gatsbyjs or #gatsbyjs.

[shannonbux]

Cool. Glad ya'll like those ideas. Twitter might get flooded, and that's great because people can search for that hashtag if they want to and then the @gatsbyjs feed is still curated and doesn't have to get overwhelmed by too many of the same tweets.

On Wed, Feb 28, 2018 at 12:32 PM, Amberley notifications@github.com wrote:

+1 discord for community learning. Also probably a good way to divert user questions from GH Issues that are more learning/usage oriented than actual bugs or issues.

+1 hashtag is probably the best way -- a dedicated hashtag for gatsby projects outside of tagging @gatsbyjs or #gatsbyjs.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/gatsbyjs/gatsby/issues/4175#issuecomment-369355707, or mute the thread https://github.com/notifications/unsubscribe-auth/Ae9o2glKJHXmspFYnsb_KHgjxNfJBVu4ks5tZanDgaJpZM4SOhLG .

[davidluhr]

Super excited for all of these improvements! I'm absolutely willing to pitch in to support any of these efforts.

[jlengstorf]

@shannonbux One piece of feedback I got from a dev who's not familiar with Gatsby:

define jobs Gatsby can do and write tutorial for each, rather than fitting it all into one mega-tutorial

I haven't dug into the specifics of the latest changes, but I wonder if there's potential in branching the tutorial to meet different use cases:

• Tutorial for creating a personal website or blog with Markdown
  • This could be the "Gatsby for Beginners"/"Intro to Gatsby" tutorial
• Tutorial for creating a website backed by a CMS (e.g. Contentful, WordPress API)
• Tutorial for creating a dynamic app (e.g. with auth)
• Tutorial for creating an e-commerce site

A lot of the early stages would overlap, but things would diverge pretty heavily depending on the goal. This might help clarify what should be in each tutorial — we'd be defining the Jobs to Be Done — and help people find exactly what they're trying to learn to do without having to filter for things that don't apply to their use case.

Does this make sense/seem reasonable?

[moonmeister]

@shannonbux @jlengstorf I think this is a great idea. I think there two ways I'm thinking this could be handled. No matter how you do it you need to make it clear to users how to access different parts and manage the massive ammount of new infomation on the site.

Method 1: Create a branch like you mentioned. I think a great example of this is the https://www.howtographql.com/ layout and branching they do. After the intro you can read more advanced theory or get down an dirty with a variety of hands on stuff. But in this case it's Blog vs. e-comerce instead of react/appolo vs react/relay.

Method 2: If you modify the existing tutorial to instead of being tutorials 1-x and make it the "Getting Started Guide"(or something) with chapters/stages. Then you can create searate e-comerce, blog, dynamic app (w/ auth), etc... tutorials in addtion to the getting started. Then when the users arrive to the end of the getting started you can give them a clear path to the more advanced tutorials.

The more I think about these I'm leaning towards option 1, I think it's maybe just a better version of option 2. Either way, I like how https://www.howtographql.com/ has laid out the graphql tutorials and it would be a good model to base a more complex set of possible learning paths for developers.

[moonmeister]

Also, I'm happy to donate my https://github.com/moonmeister/gatsby-contentful-netlify-example to this effort. If it needs modification, updating, or transfer to new ownership let me know.

[jlengstorf]

@moonmeister This is great, thanks! I think your description of Method 1 above is what I was thinking.

Kind of a choose-your-own-adventure approach to docs:

1. What is Gatsby?
2. Set up your first Gatsby site (Basics)
3. Now... what would you like to build?
   • A static marketing website or portfolio
   • A blog that's powered by Markdown
   • A website with a blog that's powered by Contentful (could be @moonmeister's starter)
   • A dynamic app with user authentication (could start with Auth0 blog)
   • An e-commerce website (Shopify?)

That way we can cover the fundamentals in a single place to avoid duplicate docs all over the place, then specialize the tutorial for 3–5 common use cases.

[shannonbux]

@moonmeister and @jlengstorf the howtographql.com illustration makes it pretty intuitive. I'd love to do a cool visual pathway like theirs, although we don't have videos so the linked text would look different that their "play" signs that appear.

Next step 1: It seems we need to brainstorm what topics fit under the first two steps that Jason mentioned above. Here's what I think would fit under those topics. Reactions?

1. What is Gatsby?
   • Short definition
   • What Gatsby is good for
   • What Gatsby may not be so good for
   • Perhaps a version of / link to the Gatsby features page
2. Set up your first Gatsby site (basics)
   • (Add an optional branch here for programming basics for those who don't know abt terminal/code editors/browser consoles)
   • Get development environment set up with node
   • Install gatsby-cli
   • install a hello-world starter
   • a few ideas for exploring and playing with Gatsby
3. Now...what would you like to build?

Next step 2: We ought to prioritize the types of sites people might build and then create separate issues for each one. Ideas on how to prioritize @jlengstorf 's list?

[jlengstorf]

@shannonbux Awesome.

RE Step 1, I think you've got it pretty nailed down. We'll probably come up with adjustments as those are fully fleshed out, but it seems like a great starting point.

RE Step 2, the good news is that we already have two of these mostly put together.

• The static site/portfolio is already more or less handled in the existing tutorial, so we'd just need to lift it out and polish it up. There's probably some benefit in updating the example site's content and design to be more portfolio-ish, but that could be deferred if it's too much work.

• The Markdown blog also already exists, and I would be devastated if we lost the "Pandas Eating Things" posts. 😄 🐼 Again, I think we just need to lift this out, polish it up, and potentially do a bit of design and code cleanup to remove the static pages from earlier in the tutorial.

For the remaining ideas, I can argue myself into thinking any of them is the most important. 😕

• Site w/Contentful seems like a really common use case (judging by the amount of content and chatter around it)
  • As a counterpoint, there are already several tutorials on hooking up Gatsby and Contentful — do we need to write another one?
• Dynamic apps w/user accounts are super important, in my opinion. Many devs I've spoken to are really surprised to hear that this is an option with Gatsby, so putting a tutorial together that shows how it's done seems like a good way to ensure this capability is front and center.
• E-commerce is probably less common than dynamic apps or CMS-driven sites, so maybe this should be dropped to the bottom of the TODO list?

[KyleAMathews]

Agree Contentful would be great tutorial as super easy to get going with + powerful + already popular.

User accounts would be excellent as well as applies to tons of things.

ecommerce I agree is less important. Also when store.gatsbyjs.org gets built — that'll be both a living demo of e-commerce + it'll be easy to turn into a tutorial.

[moonmeister]

@shannonbux I think everything @jlengstorf and @KyleAMathews has said sounds good to me. Netlify is another big CMS that could be worth a tutorial. Their documentation on the plugin is pretty good (it has defiite room for growth) so this is maybe lower on the list.

I was just looking up the "howtographql" code to see if we could use their source to build this out and realized the site is built with Gatsby! How cool...I'm sure this isn't news to you all though...any way that'll make it easy to use that model if we want. https://github.com/howtographql/howtographql

[jlengstorf]

From #4320: if it doesn't exist, we should add a prominent section on where GraphQL queries do and do not work inside Gatsby.

[jlengstorf]

@moonmeister it's news to me. 😄 Thanks for the heads up!

And good call on Netlify. I think the long-term goal should be to create a style guide so that it's easy for any third-party plugin to write a "how to use __ with Gatsby" tutorial. This'll be really important as we see more and more source plugins added to the ecosystem.

[shannonbux]

@jlengstorf @moonmeister, @amberleyromo and @KyleAMathews Questions:

• does the true beginner branch vs. quick start branch make sense visually here?
• Currently the site navigation confused a lot of interviewees btw the "Get Started" button and tutorial tab. How can we solve that?
• What do you think about finishing up with deployment/hosting options at the end of this image? (Also, I did not mean for this to give off such an alien spaceship vibe lol. We could also flip the diagram to go from left to right to be different from howtographql)

[davidluhr]

@shannonbux I really like this idea, but it may be easier to have more of a hub for the various Gatsby resources to clear up confusion around what each area of the site is for and where to begin.

I think an overall "Get Started" landing page can direct users to multiple locations based on needs/experience.

For example, there can be several links for:

• Recommended learning
• Quick start
• Tutorial
• Docs
• Etc.

Each link could be accompanied by some brief language to help guide users, such as:

Recommended learning

New to ReactJS, GraphQL...? Start with our recommend learning resources before starting the GatsbyJS tutorials.

Quick start

Ready to dive into Gatsby? Follow our Quick start guide and get a Gatsby project going in just minutes.

What are your thoughts?

[shannonbux]

See PR #4153 and see what you think, @davidluhr! @KyleAMathews and I were just discussing the merits of having a holistic landing page, like what you're describing. Django has a page like that (though it's really sparse and kind of boring, now that I think about it. Your suggestion is more robust). One downside of this holistic landing page: with the current docs nav to the left on the site, it might be overkill to give ppl a link to the docs.

The next step I'm going to do is observing ppl--I met a bunch of new devs at a React meetup this week and I'm going to observe them and what they do on their first visit to Gatsbyjs.org to see if that can shed more light into this discussion!

[moonmeister]

@davidluhr I think what you're suggesting david is exactally what we're talking about doing. But instead of a bunch of headers with descriptions we're trying to make it more intuitive (read "visual") by laying it out with the timeline. I think this is important as no one likes reading. The more pictues or graphical elements you can include to help devs follow along the better!

@shannonbux So, looking at the "howtographql" pathway I'd say any "introduction" material we want to share with everyone should be on the main pathway. Only things that are optional (see: Andvanced GraphQL) should be be on a side pathway. I'll try to describe. Basically start with a quick intro and then go into basic highlevel concepts.

1. Intro Material
2. Basic highlevel concepts for gatsby...etc..etc..
3. Location 1: Intro to NPM/Yarn/node/React (optional)
4. In depth High level concepts for gatsby (optional)
5. Location 2: Alt location for the npm/yarn/... new developer branch
6. Pathway selection for tyepe of site.

Hopefull this all makes sense. Let me know if you need clarification.

Deployment should definately be the last stage!!! I can't beleive we all forgot about that!!! That's why your paid the big $$ Shannon. :)

[shannonbux]

@moonmeister Awesome! What does "location 1" and "location 2" refer to? And why an alternate location for the npm/yarn/etc. intro?

[moonmeister]

@shannonbux location 1 & 2 was me trying to communicate that I could see the branch for new developers being placed in either location. The argument for the first position would be that we're moving from basic things to more complicated. The argument for the second location would be we're moving from theoretical to hands on as well as basic to more complicated but because that will be hands on it should still come after all theoretical sections. Make sense?

[digitaldiy]

Hope cms integration tutorials get a bit more priority as word press api integration, takes a lot of trial and error and a bit of magic to get working, the plugins documentation seems a tad out of date especially after finishing all the tutorials it really feels like being pushed in tat the deep end, great work on revamping the docs though but there is literally only one rough guide on word press integration, i do plan on adding one if (when, I'm not a defeatist not all the time any way) i can get it working but definitely think the pathway design is the best way to go , only wish life was organized a bit more like that :)

[moonmeister]

@digitaldiy That's a good point. There is a lack of good docs around 3rd party integrations.

@shannonbux I don't think it's realistic for gatsby to have to maintain docs for every conceivable 3rd party cms/plugin but is there away we could make space for community examples/tutorial contributions. Whether in the gatsby docs (maybe just adding a structure for them to plug into) or separate repos like the 3rd party plugins are done now?

[shannonbux]

Hello everyone! Any objections to me closing this issue to create new smaller issues to address these lingering ideas:

• Create a visually pleasing and clear onboarding landing page
• Make sure templates, style guides and a list of priorities exist for community tutorial contributions to aid in maintaining docs and tutorials for 3rd party integrations/plugins"
• add a prominent section on where GraphQL queries do and do not work inside Gatsby (see #4320).

[moonmeister]

go for it...good summaries

On Fri, Mar 23, 2018 at 3:39 PM, shannonbux notifications@github.com wrote:

Hello everyone! Any objections to me closing this issue to create new smaller issues to address these lingering ideas:

• Create a visually pleasing onboarding landing page
• Make sure templates, style guides and a list of priorities exist for community tutorial contributions to aid in maintaining docs and tutorials for 3rd party integrations/plugins"
• add a prominent section on where GraphQL queries do and do not work inside Gatsby (see #4320 https://github.com/gatsbyjs/gatsby/issues/4320).

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/gatsbyjs/gatsby/issues/4175#issuecomment-375816746, or mute the thread https://github.com/notifications/unsubscribe-auth/ACmrdxotYNdxjDHRaMjIQq1b8QAZ7v-_ks5thXm8gaJpZM4SOhLG .