feat(docs): Create clearer pathways in docs (#9898)

* clarify that VS Code is recommended for consistency throughout the tutorial * some recipe doc consistency * reorg. graphql-reference doesnt make sense in api reference * consistent section title * move quick start from docs landing page to dedicated doc * tweak to tutorial intro * rewrite docs landing page to be a central landing page, and reorg sidebar * style: make the linter happy * style: fix eslint errors in docs/index.js
gatsbyjs · Dec 6, 2018 · 11a33c5 · 11a33c5
1 parent 339bd1b
commit 11a33c5
Show file tree

Hide file tree

Showing 6 changed files with 129 additions and 106 deletions.
diff --git a/docs/docs/quick-start.md b/docs/docs/quick-start.md
@@ -0,0 +1,57 @@
+---
+title: "Quick Start"
+---
+
+This quick start is intended for intermediate to advanced developers. For a gentler intro to Gatsby, [head to our tutorial](/tutorial/)!
+
+## Install Gatsby's command line tool
+
+```bash
+npm install --global gatsby-cli
+```
+
+## Use the Gatsby CLI
+
+### Create a new site.
+
+```bash
+gatsby new gatsby-site
+```
+
+### Change directories into site folder.
+
+```bash
+cd gatsby-site
+```
+
+### Start development server.
+
+```bash
+gatsby develop
+```
+
+Gatsby will start a hot-reloading development environment accessible by default at `localhost:8000`.
+
+Try editing the JavaScript pages in `src/pages`. Saved changes will live reload in the browser.
+
+### Create a production build.
+
+```bash
+gatsby build
+```
+
+Gatsby will perform an optimized production build for your site, generating static HTML and per-route JavaScript code bundles.
+
+### Serve the production build locally.
+
+```bash
+gatsby serve
+```
+
+Gatsby starts a local HTML server for testing your built site.
+
+### Access documentation for CLI commands.
+
+To see detailed documentation for the CLI commands, run `gatsby --help` in the terminal.
+
+For specific commands, run `gatsby COMMAND_NAME --help` e.g. `gatsby develop --help`.
diff --git a/docs/docs/recipes.md b/docs/docs/recipes.md
@@ -2,23 +2,18 @@
 title: Recipes
 ---
 
-<!-- Basic template:
-Task to accomplish.
-1-2 sentences about it.
-Relevant links out (tutorial, doc pages, plugin readmes, etc).
+<!-- Basic template for a Gatsby recipe:
 
-Links:
-* tutorial link
-* docs link
-* additional, if needed
+## Task to accomplish.
 
-And yeah — those three things are exactly what we're thinking. A first step would be to just go through the tutorial and pull out all the basic things we teach there in a condensed form e.g. creating a site, creating a page, linking between pages, etc. -->
+1-2 sentences about it.
+Relevant links out (tutorial, doc pages, plugin readmes, etc). -->
 
 Craving a happy medium between doing the [full tutorial](/tutorial/) and crawling the [full docs](/docs/)? Here's a quick guiding reference for how to build things, Gatsby style.
 
 ## Table of Contents
 
-- [Using Unstructured Data](#using-unstructured-data)
+- [Using unstructured data](#using-unstructured-data)
 - [Gatsby project structure](#gatsby-project-structure)
 - [Using a starter](#using-a-starter)
 - [Creating pages](#creating-pages)
@@ -30,7 +25,7 @@ Craving a happy medium between doing the [full tutorial](/tutorial/) and crawlin
 - [Sourcing data](#sourcing-data)
 - [Transforming data](#transforming-data)
 
-## Using Unstructured Data
+## Using unstructured data
 
 You can use the node `createPages` API to pull unstructured data into Gatsby sites rather than GraphQL and source plugins. This is a great choice for small sites, while GraphQL and source plugins can help save time with more complex sites.
 

diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md
@@ -4,7 +4,7 @@ title: Gatsby.js Tutorial
 
 Welcome to Gatsby! We’re glad you’re here. The goal of this tutorial is to guide you through setting up and deploying your first Gatsby site using a starter template. As we walk through that process, we’ll introduce some more general web development topics, and go over the underlying structure of a Gatsby site.
 
-The full tutorial is intended to be as accessible as possible to people without much web development experience (yet!) — no need to be an expert. If you prefer to jump straight to code, feel free to skip the step-by-step tutorial and see the [quick start](/docs/) page.
+> The full tutorial is intended to be as accessible as possible to people without much web development experience (yet!) — no need to be an expert. If you prefer to jump straight to code, feel free to skip the step-by-step tutorial and see the [quick start](/docs/) page.
 
 0.  [Set Up Your Development Environment](/tutorial/part-zero/): We'll introduce you to core technologies that power Gatsby, and guide you through setting up your development environment.
 1.  [Get to know Gatsby building blocks](/tutorial/part-one/): Starting new projects, developing, and deploying sites.

diff --git a/docs/tutorial/part-zero/index.md b/docs/tutorial/part-zero/index.md
@@ -147,7 +147,9 @@ You’ll be able to visit the site locally at [**_http://localhost:8000_**](http
 
 ## Set up a code editor
 
-A code editor is a program designed specifically for editing computer code. There are many great ones out there. If you haven't worked with a code editor before, we recommend the editor used throughout this tutorial -- [**VS Code**](https://code.visualstudio.com/).
+A code editor is a program designed specifically for editing computer code. There are many great ones out there.
+
+> If you haven't worked with a code editor before, we recommend [**VS Code**](https://code.visualstudio.com/), simply because the screenshots used throughout the tutorial will match, and may be easier to follow.
 
 ### Download VS Code
 

diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml
@@ -1,9 +1,8 @@
-- title: Quick Start
+- title: Documentation
+  link: /docs/
   items:
-    - title: Getting Started
-      link: /docs/
-    - title: Starter Library
-      link: /starters/
+    - title: Quick Start
+      link: /docs/quick-start
     - title: Recipes
       link: /docs/recipes/
     - title: Awesome Gatsby Resources
@@ -105,6 +104,8 @@
     - title: Querying your data with GraphQL
       link: /docs/graphql/
       items:
+        - title: Understanding GraphQL syntax
+          link: /docs/graphql-reference/
         - title: Introducing GraphiQL
           link: /docs/introducing-graphiql/
         - title: Creating and modifying pages
@@ -113,18 +114,18 @@
           link: /docs/page-query/
         - title: Querying data in components with StaticQuery
           link: /docs/static-query/
+        - title: Using GraphQL fragments
+          link: /docs/using-fragments/
+        - title: Creating slugs for pages
+          link: /docs/creating-slugs-for-pages/
+        - title: Creating pages from data programmatically
+          link: /docs/programmatically-create-pages-from-data/
         - title: Using third-party GraphQL APIs
           link: /docs/third-party-graphql/
         - title: Adding Markdown pages
           link: /docs/adding-markdown-pages/
         - title: Adding a list of Markdown blog posts
           link: /docs/adding-a-list-of-markdown-blog-posts/
-        - title: Using fragments
-          link: /docs/using-fragments/
-        - title: Creating slugs for pages
-          link: /docs/creating-slugs-for-pages/
-        - title: Programmatically create pages from data
-          link: /docs/programmatically-create-pages-from-data/
     - title: Plugins
       link: /docs/plugins/
       items:
@@ -262,18 +263,16 @@
   items:
     - title: Gatsby Link
       link: /docs/gatsby-link/
+    - title: Gatsby Config
+      link: /docs/gatsby-config/
     - title: Gatsby Node APIs
       link: /docs/node-apis/
     - title: Gatsby Browser APIs
       link: /docs/browser-apis/
     - title: Gatsby SSR APIs
       link: /docs/ssr-apis/
-    - title: Gatsby config
-      link: /docs/gatsby-config/
     - title: Actions
       link: /docs/actions/
-    - title: GraphQL reference
-      link: /docs/graphql-reference/
     - title: Node interface
       link: /docs/node-interface/
     - title: API philosophy

diff --git a/www/src/pages/docs/index.js b/www/src/pages/docs/index.js
@@ -7,7 +7,6 @@ import { itemListDocs } from "../../utils/sidebar/item-list"
 import Container from "../../components/container"
 import EmailCaptureForm from "../../components/email-capture-form"
 import DocSearchContent from "../../components/docsearch-content"
-import presets from "../../utils/presets"
 
 class IndexRoute extends React.Component {
   render() {
@@ -18,95 +17,66 @@ class IndexRoute extends React.Component {
             <Helmet>
               <title>Docs</title>
             </Helmet>
-            <h1 id="get-started" css={{ marginTop: 0 }}>
-              Get started
+            <h1 id="gatsby-documentation" css={{ marginTop: 0 }}>
+              Gatsby.js Documentation
             </h1>
             <p>Gatsby is a blazing fast modern site generator for React.</p>
-            <p>
-              This quick start is intended for intermediate to advanced
-              developers. For a gentler intro to Gatsby,
-              {` `}
-              <Link to="/tutorial/">head to our tutorial!</Link>
-            </p>
-            <h2>
-              Install Gatsby
-              {`'`}s command line tool
-            </h2>
-            <p>
-              <code>npm install --global gatsby-cli</code>
-            </p>
-            <h2 id="using-the-gatsby-cli">Using the Gatsby CLI</h2>
+            <h2>Get Started</h2>
+            <p>There are four main ways to get started with Gatsby:</p>
             <ol>
               <li>
-                <p>Create a new site.</p>
-                <div className="gatsby-highlight" data-language="bash">
-                  <pre className="language-bash">
-                    <code className="language-bash">
-                      gatsby new gatsby-site
-                    </code>
-                  </pre>
-                </div>
+                <Link to="/tutorial/">Tutorial</Link>: The tutorial is written
+                to be as accessible as possible to people without much web
+                development experience.
               </li>
               <li>
-                <code>cd gatsby-site</code>
+                <Link to="/docs/quick-start">Quick start</Link>: The quick start
+                is intended for intermediate to advanced developers who prefer
+                to dig straight in.
               </li>
               <li>
-                <code>gatsby develop</code> — Gatsby will start a hot-reloading
-                development environment accessible at
-                {` `}
-                <code>localhost:8000</code>
+                <Link to="/docs/recipes">Recipes</Link>: A happy medium between
+                the tutorial and the quick start, find some quick answers for
+                how to accomplish some specific, common tasks with Gatsby.
               </li>
               <li>
-                Try editing the JavaScript pages in <code>src/pages</code>.
-                Saved changes will live reload in the browser.
-              </li>
-              <li>
-                <code>gatsby build</code> — Gatsby will perform an optimized
-                production build for your site generating static HTML and
-                per-route JavaScript code bundles.
-              </li>
-              <li>
-                <code>gatsby serve</code> — Gatsby starts a local HTML server
-                for testing your built site.
+                Choose your own adventure and peruse the various sections of the
+                Gatsby docs:
               </li>
+              <ul>
+                <li>
+                  <strong>Guides</strong>: Dive deeper into different topics
+                  around building with Gatsby, like sourcing data, deployment,
+                  and more.
+                </li>
+                <li>
+                  <strong>API Reference</strong>: Learn more about Gatsby APIs
+                  and configuration.
+                </li>
+                <li>
+                  <strong>Releases &amp; Migration</strong>: Find release notes
+                  and guides for migration between major versions.
+                </li>
+                <li>
+                  <strong>Conceptual Guide</strong>: Read high level overviews
+                  of the Gatsby approach.
+                </li>
+                <li>
+                  <strong>Behind the Scenes</strong>: Dig into how Gatsby works
+                  under the hood.
+                </li>
+                <li>
+                  <strong>Advanced Tutorials</strong>: Learn about topics that
+                  are too large for a doc and warrant a tutorial.
+                </li>
+                <li>
+                  <strong>Contributing</strong>: Find guides on the Gatsby
+                  community, code of conduct, and how to get started
+                  contributing to Gatsby.
+                </li>
+              </ul>
             </ol>
-            <p>
-              To see detailed documentation for the CLI commands, run in the
-              terminal <code>gatsby --help</code> and for specific commands
-              {` `}
-              <code>gatsby COMMAND_NAME --help</code> e.g.
-              {` `}
-              <code>gatsby develop --help</code>.
-            </p>
-            <h2 id="using-other-starters">Using other starters</h2>
-            <p>
-              Running <code>gatsby new</code> installs the default Gatsby
-              starter. There are
-              {` `}
-              <Link to="/starters/">
-                many other official and community starters
-              </Link>
-              {` `}
-              you can use to kickstart building your Gatsby site.
-            </p>
-            <h2 id="work-through-the-tutorial">Work through the tutorial</h2>
-            <p>
-              It walks you through building a Gatsby site from scratch to a
-              finished polished site.
-              {` `}
-              <Link to="/tutorial/">Go to the tutorial</Link>.
-            </p>
-            <div
-              css={{
-                display: `block`,
-                [presets.Tablet]: {
-                  display: `none`,
-                },
-              }}
-            >
-              <h2>Documentation</h2>
-            </div>
-            <EmailCaptureForm signupMessage="Want to keep up with the latest tips & tricks? Subscribe to our newsletter!" />
+            <EmailCaptureForm signupMessage="Want to keep up with the latest tips &amp; tricks? Subscribe to our newsletter!" />
           </Container>
         </DocSearchContent>
       </Layout>