Gatsby: [v2] docs "Recipes" doc

[shannonbux]

A stub article in new sidebar menu under Getting Started category.

Most people in usability testing expect to see some basic tasks somewhere in Getting Started, and we thought we could add them to a Recipes doc, and link to this doc in the Quick start page too.

Some tasks they want (the reason they want them is to briefly evaluate if Gatsby is easy / viable for the project they have in mind):

• creating pages
• linking between pages
• deploying

There might be some other really routine tasks that give people a sense that "oh, Gatsby is really easy to use! Ok I'll jump in"

Examples of other tasks that people like--this list of tasks on Nextjs.org's github READme: https://github.com/zeit/next.js

[shannonbux]

Some notes from a conversation about this with @KyleAMathews and Kent C Dodds and Tanner Linsley

Create a "HOW TO" page in the docs (each How To will also link to tutorials, packages, and guides). Pull these from the main tutorial as well as identify other frequent tasks e.g. the most frequently installed plugins, markdown support, etc.

[amberleyromo]

@shannonbux is this "how to" page you're describing the "Recipes" page, or something different? I definitely see this following something like the following pattern:

1. Task to accomplish.
2. 1-2 sentences about it.
3. Relevant links out (tutorial, doc pages, plugin readmes, etc).

[KyleAMathews]

Yeah, that was the name we were throwing around in that meeting.

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.

The "recipes" page is basically the tutorial aimed at experienced web developers who don't need their hand held as much. They know how to build things, they just want to know how to build things inside Gatsby.

[shannonbux]

+1 to what @kyleamathews said. How to = Recipes. In usability testing, most
people did not know what "recipes" meant, and then really liked it once
they clicked on it. So...it's a bold move that we're making and we can
adjust if it doesn't work out!

On Fri, Aug 10, 2018 at 11:39 AM, Kyle Mathews [e-mail]
wrote:

Yeah, that was the name we were throwing around in that meeting.

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.

The "recipes" page is basically the tutorial aimed at experienced web
developers who don't need their hand held as much. They know how to build
things, they just want to know how to build things inside Gatsby.

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

[akoolenbourke]

As someone who is evaluating Gatsby (and about 6 other candidates) I would absolutely LOVE this sort of thing. I think too many projects omit this type of solution-oriented content. I don't need, nor want to have to go and become a senior web developer in order to evaluate Gatsby or any other project. I have a set of requirements and I need to know, usually in a time-restricted manner, if a project will meet those requirements. Therefore simply some documentation with a huge list of "how do it do X?" for the most common tasks would a boon for evaluators and users. And it would need to be easily and quickly updatable as people have new questions.

I have spent days building a test page in Gatsby and several other candidates only to end up finding that things aren't as optimised as I want. I am willing to put that down to my inexperience but first impressions count and I would now have to go and spend many more days trying to figure all this out, only to possibly throw out a solution. I know everything takes some effort and learning, but there's a balance to be had I think. Make it simple for newcomers to get 95% of the way there.

On a related note, a caveat or limitations section that focused on common requirements that Gatsby might not be able to fulfill, or have some issues fulfilling would also be helpful. .

I understand it's hard to know what people are after but I believe there must be a set of common requirement that could be covered. One thing I would have loved to have seen is "Can Gatsby work with PHP backend and sessions?" or more general "Session based browsing and Gatsby". Which offers some solutions or says it can't do it if it's impossible.

[shannonbux]

@akoolenbourke adding your feedback to our list of research to back up why we're doing the recipes doc. Sounds like you want a list of

how do I do x?

in order to evaluate Gatsby against the requirements of your project. Is that right?

[akoolenbourke]

For me now yes that's what I would like. I found the Guides (which are great BTW) there were just a few things that would have been great to have and probably many more that can be added. I also think it wouldn't just benefit me. For instance Bootstrap is not an uncommon library of course so it would be nice to have an "integrating Bootstrap" Guide because by default it doesn't work when you use the BS JS in a component/layout. That issue is a webpack error I think but it'd still be nice for Gatsby beginners to have a quick start on it and other common scenarios.

Once I have more experience with Gatsby, I would be happy to contribute.