New intro to docs/tutorials, Part Zero of tutorials, editing names of tutorials #4153
Conversation
I'll be editing each tutorial part in a different branch. Hopefully that makes it easier to digest.
ghost
assigned 
|
huh, don't know how a picture of tom hanks ended up in here lol. It was from a way earlier PR I guess! I'm trying to delete it now. |
|
@jlengstorf ah. Now I know--I was trying to request a review from you; you must not be on list of reviewers yet. |
docs/tutorial/index.js
Outdated
| @@ -0,0 +1,56 @@ | |||
| import React from "react" | |||
There was a problem hiding this comment.
This needs converted into a markdown file. But yeah, it didn't have any reason for being a react component page.
There was a problem hiding this comment.
Yeah I was wondering why some of the index pages are js and some are md. I'll change it!
docs/tutorial/index.js
Outdated
| <ol> | ||
| <li> | ||
| <Link to="/tutorial/part-zero/">Programming basics (Part Zero)</Link>. | ||
| If you are new to programming, here's an introduction to some basics like terminal, |
There was a problem hiding this comment.
I think a more active construction would be better e.g. "go here for introductions to..."
docs/tutorial/part-zero/index.md
Outdated
| typora-copy-images-to: ./ | ||
| --- | ||
|
|
||
| Here’s a list of basic programming knowledge that is necessary before moving on in the Gatsby tutorials. If you are new to any of these things, we've provided links to helpful tutorials on these subjects!: |
There was a problem hiding this comment.
*"knowledge and tools" Seems a bit better
docs/tutorial/part-zero/index.md
Outdated
| * *Command Line:* The command line is a text interface you can open on your computer. It allows you to run commands to your computer's operating system and it's necessary to learn this skill to become a programmer. [Codecademy's Command Line tutorial](https://www.codecademy.com/courses/learn-the-command-line/lessons/navigation/exercises/your-first-command) for Mac and Linux users, and [this tutorial](https://www.computerhope.com/issues/chusedos.htm) for Windows users. Even if you are a Windows user, the first page of the Codecademy tutorial is still worth reading because it explains _what_ the command line is, not just how to use it. | ||
| * *Code editor:* Code editing programs allow you to write, edit, and save the code you'll need to write to make your website work. [VS Code Studio](https://code.visualstudio.com/download) is a great code editor for Mac, Linux, and Windows users. Refer to their docs for help on getting started. There are many other great code editors; you may want to ask other programmers what code editor they prefer. | ||
| * *Browser console:* Any internet browser you use has a console that allows you to inspect what is happening the information on each web page. This will help you figure out how to solve errors that happen while you build your website. If you are using Chrome as your web browser, here is an explanation of [how the Chrome browser console works](https://developers.google.com/web/tools/chrome-devtools/console/). If you use another web browser, search for instructions on how to access and use that browser's console. | ||
| * *[React](https://reactjs.org/)* is a JavaScript library that Gatsby uses. React knowledge is helpful but not necessary. In fact, many people are using Gatsby as a way to learn React. |
There was a problem hiding this comment.
*Prior React experience
There was a problem hiding this comment.
Hmmm I'm a bit iffy actually on that change.
There was a problem hiding this comment.
Either way. Both sound good to me.
docs/tutorial/part-zero/index.md
Outdated
| Here’s a list of basic programming knowledge that is necessary before moving on in the Gatsby tutorials. If you are new to any of these things, we've provided links to helpful tutorials on these subjects!: | ||
| * *Command Line:* The command line is a text interface you can open on your computer. It allows you to run commands to your computer's operating system and it's necessary to learn this skill to become a programmer. [Codecademy's Command Line tutorial](https://www.codecademy.com/courses/learn-the-command-line/lessons/navigation/exercises/your-first-command) for Mac and Linux users, and [this tutorial](https://www.computerhope.com/issues/chusedos.htm) for Windows users. Even if you are a Windows user, the first page of the Codecademy tutorial is still worth reading because it explains _what_ the command line is, not just how to use it. | ||
| * *Code editor:* Code editing programs allow you to write, edit, and save the code you'll need to write to make your website work. [VS Code Studio](https://code.visualstudio.com/download) is a great code editor for Mac, Linux, and Windows users. Refer to their docs for help on getting started. There are many other great code editors; you may want to ask other programmers what code editor they prefer. | ||
| * *Browser console:* Any internet browser you use has a console that allows you to inspect what is happening the information on each web page. This will help you figure out how to solve errors that happen while you build your website. If you are using Chrome as your web browser, here is an explanation of [how the Chrome browser console works](https://developers.google.com/web/tools/chrome-devtools/console/). If you use another web browser, search for instructions on how to access and use that browser's console. |
There was a problem hiding this comment.
*inspect what is happening in your web site
www/src/pages/tutorial.js
Outdated
| </p> | ||
| Hi! | ||
|
|
||
| Depending how new you are to Gatsby, you can try one of the following: |
There was a problem hiding this comment.
I'd remove the "Depending how new your are to Gatsby" part — there's lots of reasons people go one way or another that aren't due to how new they are to Gatsby. Just present the options.
Also, are you planning on changing the "get started" page? https://www.gatsbyjs.org/docs/
Actually... looking at the home page again — I'm not sure we need to change much for the getting started flow. We have a link on the front page to "Get Started" which tells how to install the cli and immediately build something. The top nav has links to the docs and tutorial. The "Get Started" page also directs people to the tutorial.
There was a problem hiding this comment.
So, the flow is a bit funky from the home page. Several people I've interviewed and other UX people have mentioned--why are tutorials and Get Started in two different places? I'm not sure exactly what to do about that. My guess is that the "Get Started" link should funnel people towards this portal with 3 choices--tutorials, quick start, docs, although having tabs across the top is really nice too. I haven't seen many sites that do a better job. I figure we can leave that decision for another day.
There was a problem hiding this comment.
Hmm interesting — my impression is most larger projects do split the getting started and the tutorial. A quick "get started" page is targeted towards advanced users or people already familiar with the project but who want a quick refresher on how to do the initial setup. E.g. you've used Gatsby at home but are setting things up at work and forgot what the CLI tool is called.
There was a problem hiding this comment.
We should perhaps mention at the top of the "get started" page the tutorial and docs to direct people that way.
There was a problem hiding this comment.
I think the difference in our case is that many of the "get started" are more of a "quickstart" (e.g. 5 minutes to install and get something running). Gatsby's get started is way more in-depth, if I'm not crossing my wires here.
There was a problem hiding this comment.
It should only take you five minutes to go through the instructions here: https://www.gatsbyjs.org/docs/ (unless you don't have node or something installed)
There was a problem hiding this comment.
People I've observed--when they get to the homepage of Gatsbyjs.org, invariable click on "Get Started" first. Then they're like, whoa. I don't understand this. OR, they install stuff, and then they're like, "hm, I need more guidance." Then they look around, and find the tutorial.
|
No additional feedback from me. What @KyleAMathews said all makes sense. |
Man, hope I got the links right. I have read the Github docs on this dozens of times and still get confused. Will need to update this doc again as we add more parts to the tutorials.
|
Deploy preview for gatsbygram ready! Built with commit e0a3681 |
|
Deploy preview for gatsbygram ready! Built with commit acb4cb8 |
|
Deploy preview for using-glamor failed. Built with commit c6769ed https://app.netlify.com/sites/using-glamor/deploys/5a8e0bebefbe5d1afec6511e |
|
ok @KyleAMathews addressed all issues in your review. |
|
Deploy preview for gatsbygram ready! Built with commit c6769ed |
|
Deploy preview for gatsbygram ready! Built with commit 20ff709 |
docs/tutorial/part-zero/index.md
Outdated
|
|
||
| Here’s a list of basic programming knowledge and tools that are necessary before moving on in the Gatsby tutorials. If you are new to any of these things, we've provided links to helpful tutorials on these subjects!: | ||
| * *Command Line:* The command line is a text interface you can open on your computer. It allows you to run commands to your computer's operating system and it's necessary to learn this skill to become a programmer. [Codecademy's Command Line tutorial](https://www.codecademy.com/courses/learn-the-command-line/lessons/navigation/exercises/your-first-command) for Mac and Linux users, and [this tutorial](https://www.computerhope.com/issues/chusedos.htm) for Windows users. Even if you are a Windows user, the first page of the Codecademy tutorial is still worth reading because it explains _what_ the command line is, not just how to use it. | ||
| * *Code editor:* Code editing programs allow you to write, edit, and save the code you'll need to write to make your website work. [VS Code Studio](https://code.visualstudio.com/download) is a great code editor for Mac, Linux, and Windows users. Refer to their docs for help on getting started. There are many other great code editors; you may want to ask other programmers what code editor they prefer. |
There was a problem hiding this comment.
It's "Visual Studio Code", not "Code Studio" ;-)
docs/tutorial/part-zero/index.md
Outdated
| Here’s a list of basic programming knowledge and tools that are necessary before moving on in the Gatsby tutorials. If you are new to any of these things, we've provided links to helpful tutorials on these subjects!: | ||
| * *Command Line:* The command line is a text interface you can open on your computer. It allows you to run commands to your computer's operating system and it's necessary to learn this skill to become a programmer. [Codecademy's Command Line tutorial](https://www.codecademy.com/courses/learn-the-command-line/lessons/navigation/exercises/your-first-command) for Mac and Linux users, and [this tutorial](https://www.computerhope.com/issues/chusedos.htm) for Windows users. Even if you are a Windows user, the first page of the Codecademy tutorial is still worth reading because it explains _what_ the command line is, not just how to use it. | ||
| * *Code editor:* Code editing programs allow you to write, edit, and save the code you'll need to write to make your website work. [VS Code Studio](https://code.visualstudio.com/download) is a great code editor for Mac, Linux, and Windows users. Refer to their docs for help on getting started. There are many other great code editors; you may want to ask other programmers what code editor they prefer. | ||
| * *Browser console:* Any internet browser you use has a console that allows you to inspect what is happening on your web site. This will help you figure out how to solve errors that happen while you build your website. If you are using Chrome as your web browser, here is an explanation of [how the Chrome browser console works](https://developers.google.com/web/tools/chrome-devtools/console/). If you use another web browser, search for instructions on how to access and use that browser's console. |
There was a problem hiding this comment.
Just a note, that whole list item is fine as it is: I wish this Google-sponsored interactive course http://discover-devtools.codeschool.com/ was still up to date (it has to be 5 or 6 years old now I believe). :-( It most probably is because the basics haven't changed, but I have a hard time recommending to link to it without checking. Had good results with a whole unit of totally untrained people.
docs/tutorial/part-zero/index.md
Outdated
| * *Browser console:* Any internet browser you use has a console that allows you to inspect what is happening on your web site. This will help you figure out how to solve errors that happen while you build your website. If you are using Chrome as your web browser, here is an explanation of [how the Chrome browser console works](https://developers.google.com/web/tools/chrome-devtools/console/). If you use another web browser, search for instructions on how to access and use that browser's console. | ||
| * *[React](https://reactjs.org/)* is a JavaScript library that Gatsby uses. Prior React experience is helpful but not necessary. In fact, many people are using Gatsby as a way to learn React. | ||
| * *GraphQL:* The Gatsby tutorials also teach you basic [GraphQL](http://graphql.org/), which is a query language (a programming language that allows you to pull data into your website). Prior GraphQL knowledge is helpful but definitely not necessary. Many people are using Gatsby as a way to learn GraphQL. | ||
|
|
There was a problem hiding this comment.
I wonder if we should explicitly mention HTML, CSS, and JS here, too? The concepts of HTML (content and structure) and CSS (presentation) might be explained relatively easy even to a total beginner…at least that's what I'd like to think; JS makes it a little tricky regarding server/client.
Something like this?
Do we need the "helpful but not necessary" part? It's starting to feel like this page is getting long and makes it seem like...wait, you really _do_ need to know how to program before building with Gatsby.
shannonbux
changed the title
|
Hey @KyleAMathews and @jlengstorf is this good to go? |
There was a problem hiding this comment.
Hey, @shannonbux — this is looking great, but there are a few things we need to fix before it's ready to merge.
- There are a couple technical issues that need to be resolved. I'm happy to help with this!
- I have a few nitpicks about phrasing. Feel free to ignore these if you disagree with my reasoning.
docs/tutorial/index.js
Outdated
| @@ -0,0 +1,13 @@ | |||
| --- | |||
| title: Gatsby.js Tutorial | |||
| --- | |||
There was a problem hiding this comment.
This needs to be converted to a .md file. It's currently ignored.
docs/tutorial/part-zero/index.md
Outdated
|
|
||
| ### Necessary tools: | ||
| * [The basics of how a website works](https://www.codeschool.com/beginners-guide-to-web-development/how-does-a-website-work) might be helpful. | ||
| * *Command Line:* The command line is a text interface you can open on your computer. It allows you to run commands to your computer's operating system. It's necessary to learn this skill to become a programmer. [Codecademy's Command Line tutorial](https://www.codecademy.com/courses/learn-the-command-line/lessons/navigation/exercises/your-first-command) for Mac and Linux users, and [this tutorial](https://www.computerhope.com/issues/chusedos.htm) for Windows users. Even if you are a Windows user, the first page of the Codecademy tutorial is still worth reading because it explains _what_ the command line is, not just how to use it. |
There was a problem hiding this comment.
This ended up being a fragment:
Codecademy's Command Line tutorial for Mac and Linux users, and this tutorial for Windows users.
How about:
For a great introduction to the command line, try Codecademy's...
docs/tutorial/part-zero/index.md
Outdated
|
|
||
| ### Helpful, yet not necessary: | ||
| * Some knowledge of HTML, CSS, and JS can be helpful. There are plenty of excellent tutorials out there; [Codecademy](https://www.codecademy.com/learn) is a good way to go. | ||
| * *[React](https://reactjs.org/)* is a JavaScript library that Gatsby uses. Prior React experience is helpful but not necessary. In fact, many people are using Gatsby as a way to learn React. |
There was a problem hiding this comment.
This feels like a bit of an understatement. 😅
React is a JavaScript library that Gatsby uses.
Maybe something more like:
React is the JavaScript framework that Gatsby uses to build pages and structure content.
Mostly I just want this to imply a stronger relationship between Gatsby and React.
www/src/pages/tutorial.js
Outdated
| </ol> | ||
| Want to learn more about Gatsby? Read the overview of Gatsby Features to see whether Gatsby is right for your project. | ||
|
|
||
| [Gatsby Features](/docs/features.js) |
There was a problem hiding this comment.
Is this page supposed to show the content of index.js above (starting with, "We’re so happy you decided to try using Gatsby.")?
Currently, this Markdown won't be processed.
@jlengstorf and @KyleAMathews addressed your suggestions! The one thing I'm still doubting is whether it's just too sad or weird to have a tutorial part zero. Does the number zero look funny to anyone else? We could just have no number for it.
|
Did you guys get this message with my commit? It's so tiny and accordioned into oblivion above.
@KyleAMathews, the Django-esque page is at |
www/src/pages/tutorial.js
Outdated
| @@ -4,47 +4,23 @@ import Link from "gatsby-link" | |||
|
|
|||
| import Container from "../components/container" | |||
|
|
|||
| export default () => ( | |||
| export default (props) => ( | |||
There was a problem hiding this comment.
The changes here should be reverted
There was a problem hiding this comment.
Or actually, this file should be removed since docs/tutorial/index.md is what is being used https://deploy-preview-4153--gatsbyjs.netlify.com/tutorial/
This should stay. It's what shows up at https://www.gatsbyjs.org/docs/ |
|
Just removed tutorials.js + formatted everything. |
|
I think this is good to go now! |
|
@shannonbux did we lose your GraphQL changes? |
|
@KyleAMathews the content of Unless I missed a conversation, I think that should go into this PR. |
|
@jlengstorf, huh, yeah it should be here. I can't figure out why it didn't
go into the commit. It's still saved in my local file!
…On Fri, Mar 2, 2018 at 3:49 PM, Jason Lengstorf ***@***.***> wrote:
@kykeamathews the docs/docs/tutorial/index.md should be showing at
/docs/. @shannonbux <https://github.com/shannonbux> and I paired up to
walk through creating a GraphQL query and reading it into the page template.
Unless I missed a conversation, I think that should go into this PR.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#4153 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/Ae9o2p5rbkjyUlpwJQA9dMuZQqsG1wZCks5tacx1gaJpZM4SMzey>
.
|
|
My code editor is showing 1 unsaved change, but clicking save doesn't make
the notification go away.
…On Fri, Mar 2, 2018 at 3:55 PM, Shannon Soper ***@***.***> wrote:
@jlengstorf, huh, yeah it should be here. I can't figure out why it didn't
go into the commit. It's still saved in my local file!
On Fri, Mar 2, 2018 at 3:49 PM, Jason Lengstorf ***@***.***>
wrote:
> @kykeamathews the docs/docs/tutorial/index.md should be showing at
> /docs/. @shannonbux <https://github.com/shannonbux> and I paired up to
> walk through creating a GraphQL query and reading it into the page template.
>
> Unless I missed a conversation, I think that should go into this PR.
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <#4153 (comment)>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/Ae9o2p5rbkjyUlpwJQA9dMuZQqsG1wZCks5tacx1gaJpZM4SMzey>
> .
>
|
|
Sorry — stepped out for lunch. tutorials.js wasn't necessary since all markdown files in docs/ already have pages created for them. So I removed it in my commit a bit earlier 1789b5c |
|
@KyleAMathews Ah, I overcomplicated things for @shannonbux because it didn't occur to me to delete Sorry about that! I pulled this branch locally and fired it up — it looks great. Awesome work, Shannon! |
|
@jlengstorf it was great practice and a huge help to me regardless! Thanks!!
…On Sat, Mar 3, 2018 at 10:38 PM Jason Lengstorf ***@***.***> wrote:
Merged #4153 <#4153>.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#4153 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/Ae9o2lg9fyrqBJc0bmAwmbSyo50XQhMkks5ta33pgaJpZM4SMzey>
.
|
| @@ -0,0 +1,23 @@ | |||
| --- | |||
| title: Programming Basics (Part Zero) | |||
There was a problem hiding this comment.
I think this is less of a "programming basics" and more of a "development environment" primer/introduction. Would you agree? Linking back to this comment, I see this being more of a structured walkthrough (with a targeted intro to concepts as they arise), rather than a listing of concepts.
I'll be editing each tutorial part in a different branch. Hopefully that makes it easier to digest.