Improvements to tutorial part zero #9522

tlent · 2018-10-29T14:47:23Z

This PR:

Simplifies the headings and makes them more clear and consistent
Clarifies some of the sentences I thought might be confusing
Improves the summary at the end to cover everything done
Expands the Git section to better explain how to install it. I added links to the Atlassian guide for installing Git because I found they had the best explanations. The linked guides include a check that git is working so I did not include that.
Adds an optional link to learn more about Git and Github to the Git section and removes a later link serving the same purpose

amberleyromo · 2018-10-29T15:00:52Z

I'll leave this to @shannonbux to double-check the headings, but I think these changes make sense 👍

yeskunall

I left some comments. Thanks for this PR! It's great work! 💖

yeskunall · 2018-10-29T22:39:41Z

docs/tutorial/part-zero/index.md


-If your system does not have Git installed, install it from the [**Git downloads page**](https://git-scm.com/downloads).
+> 💡 You will not need to use Git yourself to work with Gatsby, but it is a very useful tool to know about as a developer. If you are interested in learning more about version control, Git, and Github, check out Github's [Git Handbook](https://guides.github.com/introduction/git-handbook/).


If we're going to make this change, then we also need to mention that git is used everywhere else when cloning gatsby-starters.

Yes, could you please clarify when Git is not necessary? It is necessary for many things people do with Gatsby, such as using starters and contributing to Gatsby.

Good point this sentence was not very clear. Hopefully the new version is better. The reason I have included it is to make sure nobody reading gets overwhelmed or too distracted by learning Git or all of its commands that the handbook talks about

yeskunall · 2018-10-29T22:43:00Z

docs/tutorial/part-zero/index.md


-## Install the Gatsby CLI
+## The Gatsby CLI


The "the" here is unnecessary. What I mean is, it adds no meaning. The Gatsby CLI would make sense in a world where this is the only Gatsby CLI ever. 😆

You are right I have changed this title and other references to it to make it more clear that it is not the only Gatsby CLI

yeskunall · 2018-10-29T22:44:31Z

www/src/data/sidebars/tutorial-links.yaml

-        - title: Install the Gatsby CLI
-          link: /tutorial/part-zero/#install-the-gatsby-cli
+        - title: The command line
+          link: /tutorial/part-zero/#the-command-line


The hyperlinks seem more disconnected to the doc/top we're talking about 🤔

shannonbux

Hello @tlent! Lots of awesome edits here! Left a few requested changes. One overall change is to keep the word "install" in the headers that show up in the doc-links sidebar (so you'll have to leave the sidebar as is and then revert some of the changes in the doc itself. It's always a battle (in my mind) between making things shorter and making them clearer. Usually shorter = clearer; however, in this case the verbs help people know what to expect when they're scanning the sidebar.

shannonbux · 2018-10-30T04:08:19Z

docs/tutorial/part-zero/index.md


-If your system does not have Git installed, install it from the [**Git downloads page**](https://git-scm.com/downloads).
+> 💡 You will not need to use Git yourself to work with Gatsby, but it is a very useful tool to know about as a developer. If you are interested in learning more about version control, Git, and Github, check out Github's [Git Handbook](https://guides.github.com/introduction/git-handbook/).


Yes, could you please clarify when Git is not necessary? It is necessary for many things people do with Gatsby, such as using starters and contributing to Gatsby.

shannonbux · 2018-10-30T04:08:30Z

docs/tutorial/part-zero/index.md


-## Install the Gatsby CLI
+## The Gatsby CLI


shannonbux · 2018-10-30T04:10:05Z

docs/tutorial/part-zero/index.md


-Now you can use the gatsby-cli tool to create your first Gatsby site. Using the tool, you can use “starters”, or partially built sites with some default configuration, to help you get moving faster on creating a certain type of site. The “Hello World” starter you’ll be using here is a starter with the bare essentials needed for a [Gatsby](/) site.
+Now you are ready to use the Gatsby CLI tool to create your first Gatsby site. Using the Gatsby CLI you can download “starters” (partially built sites with some default configuration already done) to help you get moving faster on creating a certain type of site. The “Hello World” starter you’ll be using here is a starter with the bare essentials needed for a Gatsby site.


This is a bit wordy. Try "Now you are ready to use Gatsby CLI to create your first Gatsby site. Using the tool, you can download..."

And then remove the phrase "already done." Default configuration implies the same meaning.

You are right I have made these changes in the new version

shannonbux · 2018-10-30T04:10:33Z

docs/tutorial/part-zero/index.md


-### ✋ Create a Gatsby site
+### ✋ Create the site


Hm, I like the previous heading more because it's clearer

This reverts commit 511bc37.

…atsby CLI

tlent · 2018-10-30T18:09:19Z

Thank you for the feedback! I have reverted the heading changes to have verbs again and replied to the other suggestions above.

calcsam · 2018-11-12T08:38:44Z

docs/tutorial/part-zero/index.md


 The command line is a text-based interface used to run commands on your computer. (You’ll also often see it referred to as the terminal. In this tutorial we’ll use both interchangeably). It’s a lot like using the Finder on a Mac, or Explorer on Windows. Finder and Explorer are examples of graphical user interfaces (GUI). The command line is a powerful, text-based way to interact with your computer.

+### ✋ Familiarize yourself with the command line


this should probably not be here?

I think they are following suite with the rest of the doc.

shannonbux · 2018-11-12T22:00:13Z

I edited the headers to streamline them and removed the emojis in headers for now. We could add them back in later. Thanks @tlent and @calcsam!

* Improved headers and clarity in tutorial part zero * Further simplify headings * Improve Git section * Improve the summary * Add optional link explaining git * Remove other reference to learn about git * Fix titles and links to match new headings * Clarify that git only needs to be installed to use Gatsby * Mention that the git handbook also explains Github * Revert "Fix titles and links to match new headings" This reverts commit 511bc37. * Revert the headings back to having verbs * Reword references to Gatsby CLI to make it clear it is not the only Gatsby CLI * Change 'Create a Gatsby site' heading back * Fix title to match heading * Clarify git sentence * Add missing space

tlent added 9 commits October 28, 2018 22:15

Improved headers and clarity in tutorial part zero

9504630

Further simplify headings

12ce759

Improve Git section

6f0c559

Improve the summary

cb80cd5

Add optional link explaining git

28a1128

Remove other reference to learn about git

727bc61

Fix titles and links to match new headings

511bc37

Clarify that git only needs to be installed to use Gatsby

f82e167

Mention that the git handbook also explains Github

eff821c

tlent requested a review from a team October 29, 2018 14:47

tlent requested a review from a team as a code owner October 29, 2018 14:47

yeskunall reviewed Oct 29, 2018

View reviewed changes

shannonbux suggested changes Oct 30, 2018

View reviewed changes

tlent added 6 commits October 30, 2018 13:06

Revert "Fix titles and links to match new headings"

136273c

This reverts commit 511bc37.

Revert the headings back to having verbs

4e4577d

Reword references to Gatsby CLI to make it clear it is not the only G…

fdd039e

…atsby CLI

Change 'Create a Gatsby site' heading back

56714e8

Fix title to match heading

67859b7

Clarify git sentence

1660a7e

Add missing space

c159d3b

calcsam reviewed Nov 12, 2018

View reviewed changes

shannonbux approved these changes Nov 12, 2018

View reviewed changes

Merge branch 'master' into patch-2

0a8c114

shannonbux merged commit 3fe6287 into gatsbyjs:master Nov 12, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improvements to tutorial part zero #9522

Improvements to tutorial part zero #9522

tlent commented Oct 29, 2018

amberleyromo commented Oct 29, 2018

yeskunall left a comment

yeskunall Oct 29, 2018

shannonbux Oct 30, 2018

tlent Oct 30, 2018

yeskunall Oct 29, 2018

shannonbux Oct 30, 2018

tlent Oct 30, 2018

yeskunall Oct 29, 2018

shannonbux left a comment

shannonbux Oct 30, 2018

shannonbux Oct 30, 2018

shannonbux Oct 30, 2018

tlent Oct 30, 2018

shannonbux Oct 30, 2018

tlent commented Oct 30, 2018 •

edited

calcsam Nov 12, 2018

yeskunall Nov 12, 2018

shannonbux commented Nov 12, 2018 •

edited


		If your system does not have Git installed, install it from the [Git downloads page](https://git-scm.com/downloads).
		> 💡 You will not need to use Git yourself to work with Gatsby, but it is a very useful tool to know about as a developer. If you are interested in learning more about version control, Git, and Github, check out Github's [Git Handbook](https://guides.github.com/introduction/git-handbook/).


		Now you can use the gatsby-cli tool to create your first Gatsby site. Using the tool, you can use “starters”, or partially built sites with some default configuration, to help you get moving faster on creating a certain type of site. The “Hello World” starter you’ll be using here is a starter with the bare essentials needed for a [Gatsby](/) site.
		Now you are ready to use the Gatsby CLI tool to create your first Gatsby site. Using the Gatsby CLI you can download “starters” (partially built sites with some default configuration already done) to help you get moving faster on creating a certain type of site. The “Hello World” starter you’ll be using here is a starter with the bare essentials needed for a Gatsby site.


		The command line is a text-based interface used to run commands on your computer. (You’ll also often see it referred to as the terminal. In this tutorial we’ll use both interchangeably). It’s a lot like using the Finder on a Mac, or Explorer on Windows. Finder and Explorer are examples of graphical user interfaces (GUI). The command line is a powerful, text-based way to interact with your computer.

		### ✋ Familiarize yourself with the command line

Improvements to tutorial part zero #9522

Improvements to tutorial part zero #9522

Conversation

tlent commented Oct 29, 2018

amberleyromo commented Oct 29, 2018

yeskunall left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shannonbux left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tlent commented Oct 30, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shannonbux commented Nov 12, 2018 • edited

tlent commented Oct 30, 2018 •

edited

shannonbux commented Nov 12, 2018 •

edited