Some major changes #3388
Some major changes #3388
Conversation
I streamlined this to just one option: CSS Modules. I saved all the text that I took out in case we need it later or want to put it back in. One edit that I wrote in my notebook, which I now don't understand, reads: "Tell people to create `src/pages/about-styled-components.js`
ghost
assigned 
|
Deploy preview ready! Built with commit e5ed00a |
There was a problem hiding this comment.
I really like in general the idea of simplifying this part of the tutorial. Are we sure it's confusing though? It's very clear that the Glamor/Styled Components parts are duplicates and I think it's really important that we introduce css-in-js at this point. Have you heard negative feedback from people about this part of the tutorial?
It'd be nice if there was a clear winner in this space that we could push people to. I feel 90% confident that css-in-js will win so want to make sure we're introducing people to it.
| @@ -108,8 +108,9 @@ plugins. | |||
|
|
|||
| ## Installing your first Gatsby plugin | |||
|
|
|||
| Let's start by creating a new site. Similar to Part One, run the following to | |||
| create a new site. | |||
| Let's start by creating a new site. At this point it probably makes sense to close the terminal window(s) you used to build tutorial-part-one so that you don't accidentally start building tutorial-part-two in the wrong place. If you don't close tutorial-part-one prior to building tutorial-part-two, you will see that tutorial-part-two appears at localhost:8001 instead of localhost:8000. | |||
docs/tutorial/part-two/index.md
Outdated
| @@ -229,8 +230,8 @@ Ah, this is starting to look nice! | |||
| What we're seeing here is the default CSS Typography.js produces. We can easily | |||
| customize it, however. Let's do that. | |||
|
|
|||
| In your site, create a new directory at `src/utils`. There create a file named | |||
| `typography.js`. In it, add the following code. | |||
| In your site, create a new directory at `src/utils` (hint: in code editors, creating a new directory looks like creating a new folder). In that directory, create a file named | |||
There was a problem hiding this comment.
a directory is the same thing as a folder :-)
If this is confusing, let's make sure to use the same word throughout the tutorial (and documentation).
There was a problem hiding this comment.
I believe directory is more standard in this industry. "folder" seems so non-professional.
|
*Re: three styling options*
Reducing styling options from three to one is a change I wrote down after
discussing them with you in Berkeley. You mentioned that since CSS-in-JS is
controversial and uncommon (as yet), maybe we could focus on CSS Modules.
Totally fine to include all three if you want.
Most people didn't mention struggling with Part Two specifically, although
struggles with CSS is in the top 10 pain points for Gatsby so far (most
people said they just don't know enough about it). One student I interviewed
in Germany (LekoArts) did mention feeling overwhelmed by Part Two and
suggested that it be divided into two tutorials (one about Typography and
one about CSS). This is what he said: "I personally think that Part Two
should be split up and the Styling have its own Part. If you have no idea
what the styling in React looks like (and your background is plain
css/scss) this can be a bit overwhelming. I also re-read it multiple times
to get the gist of every possibility."
So I'm totally fine with leaving in all three options if they are
important; then I would just focus on clarifying the wording (I can reach
out to LekoArts for more feedback).
*Re: directory = folder*
If the audience consists of some portion of true beginners to programming,
they will not know that a directory is a folder. But I guess experienced
programmers would call it a directory, I assume?. So that's why I used
both...but that's messy. So should we just call it a folder??
And this brings up a larger issue of how much basic stuff we should teach
in these tutorials. For example, how terminal works, basic terminology for
a code editor, the basic workflow of building a website. This is all stuff
I didn't know and have been adding into the tutorials, but if it makes more
sense to have a "Tutorial Zero" for this kind of stuff, I'm open to that.
It seems to me that the best option would probably be to add "Tutorial
Zero" with some basic resources and best practices, and then refer back to
Tutorial Zero along the way through the other tutorials (not too often,
just at critical moments).
…On Tue, Jan 2, 2018 at 1:45 PM, Kyle Mathews ***@***.***> wrote:
***@***.**** requested changes on this pull request.
I really like in general the idea of simplifying this part of the
tutorial. Are we sure it's confusing though? It's very clear that the
Glamor/Styled Components parts are duplicates and I think it's really
important that we introduce css-in-js at this point. Have you heard
negative feedback from people about this part of the tutorial?
It'd be nice if there was a clear winner in this space that we could push
people to. I feel 90% confident that css-in-js will win so want to make
sure we're introducing people to it.
------------------------------
In docs/tutorial/part-two/index.md
<#3388 (comment)>:
> @@ -108,8 +108,9 @@ plugins.
## Installing your first Gatsby plugin
-Let's start by creating a new site. Similar to Part One, run the following to
-create a new site.
+Let's start by creating a new site. At this point it probably makes sense to close the terminal window(s) you used to build tutorial-part-one so that you don't accidentally start building tutorial-part-two in the wrong place. If you don't close tutorial-part-one prior to building tutorial-part-two, you will see that tutorial-part-two appears at localhost:8001 instead of localhost:8000.
💯
------------------------------
In docs/tutorial/part-two/index.md
<#3388 (comment)>:
> @@ -229,8 +230,8 @@ Ah, this is starting to look nice!
What we're seeing here is the default CSS Typography.js produces. We can easily
customize it, however. Let's do that.
-In your site, create a new directory at `src/utils`. There create a file named
-`typography.js`. In it, add the following code.
+In your site, create a new directory at `src/utils` (hint: in code editors, creating a new directory looks like creating a new folder). In that directory, create a file named
a directory is the same thing as a folder :-)
If this is confusing, let's make sure to use the same word throughout the
tutorial (and documentation).
—
You are receiving this because you were assigned.
Reply to this email directly, view it on GitHub
<#3388 (review)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/Ae9o2ho5MV-URm_Ls7BrNhhmnfPu7k_1ks5tGpWAgaJpZM4RQ3eC>
.
|
docs/tutorial/part-two/index.md
Outdated
| This unfortunate restriction can lead to elaborate (and often confusing) | ||
| selector naming schemes. | ||
| Note: CSS-in-JS is another viable method for styling components which solves many of the problems with | ||
| traditional CSS. We don't have room to focus on it in this tutorial, so we'll point you to the following resources for backgroung reading on CSS-in-JS: |
|
I'm not aligned on what the entire goal for this tutorial is (or your opinion on CSS-in-JS), but personally do think it really muddies one of the main resources on how to use Gatsby with such an optional/opinionated tech, especially multiple flavors. I think it'd be stronger with none (instead share the simplest, most standard styling method) or one (your preferred method). |
|
Please don't remove the section about CSS-in-JS. I'm admittedly biased, but I think it's premature to "bless" a particular styling solution. The community is still figuring it out. |
Hmmmm yeah — it is needlessly confusing to have all three. Here's a different idea — how about we trim things back to just CSS Modules like this PR does but we take the glamor/styled components and move them into mini tutorials on separate pages and link to them so if people want to see what using css-in-js w/ Gatsby is like, they can try those. How's that sound? |
yeah! Or perhaps a "glossary" of terms that Gatsby uses — we could even get fancy and add hover explanations for potentially confusing ideas. |
|
I do like the idea of having lots of mini-tutorials that can be linked to lots of places. The main tutorial should be a bright path through the heart of learning Gatsby but be composed of multiple shorter tutorials + there should be lots of branches off the mainline for people to explore. |
|
Yeah. Best practice for beginners is to give them basically one clear path,
and then enable them to specialize or become more expert in areas of their
choice...
Experts tend to need a giant reference tool, while beginners need a
step-by-step process.
…On Wed, Jan 3, 2018 at 3:22 AM Kyle Mathews ***@***.***> wrote:
I do like the idea of having lots of mini-tutorials that can be linked to
lots of places. The main tutorial should be a bright path through the heart
of learning Gatsby but be composed of multiple shorter tutorials + there
should be lots of branches off the mainline for people to explore.
—
You are receiving this because you were assigned.
Reply to this email directly, view it on GitHub
<#3388 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/Ae9o2lOp5sd-YoAwr4-HoRJRqXL-RJxDks5tG1TQgaJpZM4RQ3eC>
.
|
|
FWIW... my vote.... @shannonbux when I went through this part of the tute many months ago, I benefited from the compare/contrast aspect of the CSS. But I also agree with you that offering too many options could be debilitating. I like the middle ground... choose one then put the other two in another section that's broken out. At the top of Part Two, add a note, something like "To learn two alternative ways to use CSS with Gatsby, click here" ... or something along those lines. |
|
Yeah, let's keep the tutorial simple with one choice but offer the other two options as mini-tutorials for people who are ready for that. *Side note: if you read through the research I just linked to, you'll also notice there are sort of 7 deadly sins of online tutorials, some of them being excessive hyperlinks (i.e. rabbit holes, which are terrible for novices) and attention splitting (e.g. having to toggle between multiple screens whilst going through the tutorial) |
|
A relevant comment from @NerdCowboy just now: "I’m a bit confused why css modules isn’t listed on the plugins page—is that just apart of Gatsby core? Both Glamor and Styled Components are listed in the plugins page, but CSS Modules is missing (though there’s now a typescript css modules plugin listed). The only place I can find any information on CSS Modules is in the tutorial—something not everyone will go through. So even if it is technically apart of Gatsby core, I would still expect to find some documentation even if it’s simply just mentioning the file’s naming scheme and linking to the official css-modules plugin for full documentation." |
|
Ok, just created a PR to create mini-tutorials for Glamor and Styled Components. Wondering if the code examples make sense when they are not part of a bigger tutorial (in other words, will the code examples make sense to someone who is not using the gatsby tutorial-part-two starter? |
Now they are separate mini-tutorials.
|
Made a few tweaks but looks really good! Thanks for the extensive review/surgery here! I think this will really help streamline the flow through this part of the tutorial. |
* Some major changes I streamlined this to just one option: CSS Modules. I saved all the text that I took out in case we need it later or want to put it back in. One edit that I wrote in my notebook, which I now don't understand, reads: "Tell people to create `src/pages/about-styled-components.js` * Update index.md * Reintroducing Glamor and Styled Components as "bonus" items Now they are separate mini-tutorials. * Update index.md * Update index.md
I streamlined this to just one option: CSS Modules. I saved all the text that I took out in case we need it later or want to put it back in.
One edit that I wrote in my notebook, which I now don't understand, reads: "Tell people to create
src/pages/about-styled-components.js