Documentation Reorganization Project

[meganesu]

Hello all, happy Thursday!

I’m here to make an exciting announcement: we’re revamping the Gatsby documentation!

TL;DR:

1. We’re reorganizing our existing documentation!
   • To limit the number of moving pieces, community contributions for docs will be temporarily paused, starting today. PRs that add new docs will not be accepted at this time. PRs that update existing docs will be reviewed on a case-by-case basis.
2. We want to hear your feedback!
   • Comment below to tell us your thoughts on our docs and your experience learning Gatsby.
   • Or fill out this contact form to give feedback on the new docs site once we have a prototype!

Why do we need to restructure the docs?

We’ve heard repeatedly from the community that Gatsby is a powerful tool, but it has a steep learning curve. We want to make it easier to get started with Gatsby. And that means having documentation that helps y’all find the information you need when you need it.

After taking a comprehensive look at our documentation, we’ve identified the following areas for improvement:

• Add a better overall structure.
  • The last time we updated our docs architecture was over two years ago.
  • Since then the amount of documentation has increased by a factor of around 10 (yay!), but as a result it’s become harder for many people to find what they need.
  • Most software architectures need refactoring once the amount of data they process increases by a 10x factor. The same goes for content architectures.
• Make sure information on each topic is consistent and non-duplicated.
  • We’ve seen instances where our docs give conflicting information at different places, or in which the same piece of information is given for unclear reasons in multiple places.
  • We want to make sure that there is a single source of truth for each topic, and that the information included is easy to understand.
• Clearly delineate the different kinds of information contained in the docs.
  • There are four kinds of documentation: tutorials, how-to guides, explanations, and reference material.
  • Our current docs tend to contain some of each, but we’ve noticed it often blends into each other without clear demarcation, which can be disorienting for users.

What To Expect

I’ll be working with @calcsam to release this work in a few different chunks. We’re currently in the process of taking inventory of all our existing docs. From there, we’re going to reorganize our existing docs into more distinct categories. After that, we’ll work on cleaning up individual pages and sections.

As of today, we are temporarily putting all community documentation contributions on hold. We’ve got a lot of existing docs that we’re shuffling around, and we don’t want to add any more moving pieces just yet. As a result, pull requests that add new docs will not be accepted at this time. Updates to existing docs will be reviewed on a case-by-case basis.

We’re handling this first pass at restructuring everything internally, so that we can maintain consistency. Once the new docs structure is in a stable place (hopefully by early 2021), we’ll open our documentation back up to community contributions.

How You Can Help

At the end of the day, this project only succeeds if it makes your lives easier. We’d love to hear from you so that we can make sure our changes best serve you and the community.

• Share your opinions about our documentation. Put them as a comment in this post. Bonus points if you share your experiences from when you were first learning Gatsby. Be brutally honest - you won’t hurt our feelings! (Okay, maybe a little, but we’ll get over it.)
• Give us feedback on the new architecture. Fill out this contact form, and we’ll reach out to you once we have a prototype. We’d especially love to hear from people who are new to Gatsby! Our hope is that we can get feedback from folks at various points in our work, so that by the time we release a final product, we’re confident that it’s going to be just what the community needs.

Thank you in advance for your feedback and for being part of our community! 💜

[axeldaguerre]

When i was starting learning Gatsby i struggled and gave up for few month, so why ? :
Unfortunately i am someone who need to understand all layers of something to understand it. And when we start the tutorial we mostly try to build a workable site without going deep on the architecture of GatbyJS.
For most people i am pretty sure it is what you have to do, and maybe it is what you need to do to make GatsbyJS easier to learn, but for developers like me it just makes it harder to learn.
I think it was only why i have struggled to learn it, when i came back i had a "click" and it was easy, can't tell you why :)

Now the good :
Find ressource is easy in my opinion, mostly thanks to the research bar and is efficiency. Structure of the documentation can be better for sure but it mostly miss more stuff for me.
Blog posts are very good quality and helps a lot to give extra ressources (so maybe documentation need to be more provided ?

[axeldaguerre]

To be honest it was not because documentation changed, it was me, you know like when you are on a piece of art, can't figure how you can make it better, you put it on the side for few days and come back and you have solved it !
I can't find the thing that made me that "click" but definitely you blog helps me for sure, during my first start i didn't read it.
So again maybe we need more topics and deeper stuff in the documentation, can't tell you more sorry.
Thank you all for doing fabulous work with GatsbyJS it is thanks to you i didn't quit web development, i was suck of all the convulsion of internet at that time, but GatsbyJS released me !

[LekoArts]

Have you read https://www.gatsbyjs.com/docs/gatsby-internals/ and https://www.gatsbyjs.com/docs/conceptual-guide/ in trying to understand how Gatsby works or didn’t you find this at all for example?

[axeldaguerre]

Thank you for the answer, i didn't find it in the beginning no, i think because it was too far from the beginning, so maybe we can give at the beginning a link for that for the first introduction in the gatsby's documentation ?

[muescha]

I'm really interested in this point. What was it that finally made things "click" for you? Was it related to a particular concept or part of Gatsby?

For me the "click" was a video (maybe an embedded egghead) I found in the docs where a starting point was a plain HTML/React site and then step by step the Gatsby components are added. This explained the Gatsby components more clear and revealed for me the unclear automagic things. I think this video should be placed more at the beginning in the jump start and in the tutorial section. Or the content of the video should be an written (tutorial?) page

It's still so hidden somewhere in docs pages so I can't find it now.

[meganesu]

Thanks @muescha! I'll poke around and see if I can find that video. We're planning on revamping the tutorial in the near future, so that will be a good resource to use for inspiration!

[FelixMildon]

The docs are the main reason why I choose Gatsby as my favorite framework.

If starters could be in the main menu next to themes and recipes that would be cool. Thankfully I now know to look up starters in the docs search.

Many thanks for the great work.

[meganesu]

Thanks for the suggestion! I know the team has talked internally a bit about rethinking the way we organize starters, so there will probably be some future improvements to that part of the site after this project.

The docs are the main reason why I choose Gatsby as my favorite framework.

I'd love to hear more about this. What specifically was it that you liked about our docs? Was there one section in particular that you used most often? (It's helpful for us to know what people already like so that we know what to keep!)

[FelixMildon]

The reference guide is my new favourite section. Everything else is good but I was struggling to learn gatsby-image for ages until I came across the reference guide ("working with images" and "gatsby-image").

The plugin docs were confusing and I'm yet to really understand a the gatsby-image recipe however with experience I may come to enjoy recipes. Because recipes is how do do something is different ways. The choice must of been too much for my brain

[ebarti]

Hello Gatsby team. Thanks for all the awesome work.

I started learning Gatsby about a month ago, so I still am pretty much a novice. On a general note, I found the documentation structure rather confusing. The side menu does not help much, as it is - IMO - quite oversized. The search function is also not very good, as the number of results returned is limited to 5 and cannot be further expanded (I guess we'll always have google).

At times I have gotten frustrated because it seems like most of the documentation pages are tailored to tackling specific problems individually. However, aggregating the individual solutions of those problems onto a single project might lead to incompatibilities that are either not well documented or not documented at all.

Additionally, I think there needs to be a purge/upgrade of anything that is not yet up to date in best practices or style. Sometimes I have looked at code and wondered should I take this as a reference or is it outdated?

To be honest it has been great for the most part, and I am hoping my feedback is of any help to the team. I am actually looking forward to contributing to the project once I get a better grasp of it all 😄

Cheers!

[axeldaguerre]

The "only 5 results" is the only complaint about result ?
Because I found the results so accurate in my case, i always use it, it works across all the site (blog, plugins, documentation) that i don't need to use the sidebar,
what do you think ?

[meganesu]

@ebarti, thanks for that feedback. (And welcome to Gatsby! We're excited to have you 💜)

Totally agree, the existing docs site is confusing, both for new and experienced Gatsby users! One of the big things we're trying to accomplish in this project is making the structure more intuitive (and the sidebar less overwhelming). We're hoping to tackle the search implementation at some point in the future, but we're considering it out of scope for this first chunk of work.

We should have a rough prototype of the new docs site sometime next week. (Keep an eye on this discussion for updates.) We'd love to hear your thoughts on the new structure, especially as a new Gatsby user!

[meganesu]

Project Update 🗣

We have our first prototype of the new docs site! It's still a work in progress (we're still styling and moving around the content), but it should at least give you a sense of the new structure.

The major changes so far have been related to the left sidebar, the top navigation, and the content of the landing pages for each section.

We'd love your feedback! If you can spare 30 minutes for an user interview, you can use this Calendly link to schedule something in the next few weeks. Or you can respond in this discussion.

• What do you like about this new structure?
• What do you dislike? What is confusing?
• Does the content in each doc type (Tutorial, How-To, Reference, Conceptual) match what you would expect to see there?
• Is this an improvement over the current docs? If not, what other improvements would you like to see?

Thanks in advance for your feedback! We're excited to keep making improvements. 💜💪

[meganesu]

(Update: I changed the prototype URL in the comment above, so now it should always have the most up-to-date changes!)

[nina-py]

Hi @meganesu, I'm quite new to Gatsby - have been tinkering with it for a few months on side projects. The revamped documentation looks great! I especially like that it's easy to progress from the tutorials, for example, to the guides - on the current site you have to use the drop-down menu to progress to another part of the docs once you're inside the tutorials section.

I never noticed the Conceptual Guide before - now it's very prominent. It's on my reading list now that I've discovered it. I'm bookmarking the prototype to use as reference from now on, and may come back to this thread with more feedback later on.

I have a related question - what are your plans for community translations? They've been about a year or so in the works, some took off more than others but even those that have had many pages translated (i.e. the Brazilian Portuguese version) have not yet been incorporated into the official docs.

[meganesu]

Hi @nina-py, welcome to Gatsby! 💜

Thanks for the feedback! We'd definitely love to hear any other thoughts or ideas you have while you're digging into the docs.

re: community translations, those (and all community docs contributions) are on hold for now, while we work on the docs reorg project. For total transparency, the translation work was started before I joined Gatsby, so I'll have to do some context gathering before we're ready to pick that effort back up. Stay tuned!

[shoxton]

what happened to the themes library? i cant find them

[meganesu]

Hi @shoxton! Are you referring to the plugin library? You can search for Gatsby themes there: https://www.gatsbyjs.com/plugins?=gatsby-theme

[Leeoku]

Hi Megan, new to Gatsby/React.

Trying the tutorial 2 for styling in Gatsby. The user component has avatar images linked to some amazon buckets. However they don't seem to work and lead to a 403 image.

In addition, the console.log(styles) in ./about-css-modules.module.css I have doesn't match with the tutorial. It's missing src-pages. I verified the file structure matches

[meganesu]

Hi there @Leeoku. Welcome to Gatsby :)

Thanks for flagging that. Looks like someone opened an issue for the same problem, if you want to keep tabs on a fix: #28974. In the meantime, feel free to swap out those URLs for whatever images you want!

Let me know if you run into anything confusing in the tutorial. We're just starting the process of rewriting it, so any suggestions or feedback you have on the current one is appreciated!

[Leeoku]

I'm not sure how I got to this link, possibly from a video I found on youtube. I noticed it's not shown in the left menu bar and how to navigate back to it other than typing the URL. The current layout is great for existing articles but for stuff that isn't, it's just confusing.

[meganesu]

Ah, yeah, thanks for pointing that out. Many of our old docs are now "orphans" - they weren't essential enough to make it into our new content architecture, but we also didn't want to delete them for legacy reasons. Agreed that it's not the best experience! Right now, you can get to those orphaned docs by using the search bar (or by accessing the URL directly, as you mentioned).

Is there something else you expected to see for the layout of those orphaned pages? Trying to figure out what a better experience would be.

[Leeoku]

As a beginner, the answer is I don't know. How am I supposed to know what already exists/what to search for? If I find these links, are those still good examples? (Ex the Awesome Resources page with podcasts, videos etc). My understanding from what I read is How to guides replaces recipes

If the existing new docs are to be the gold standard but the old docs kept for legacy reasons, I'd at least appreciate a tab/category/heading to at least document which docs are legacy.

Ex. Here is a legacy tab with these docs as legacy. They still do reflect good Gatsby practice and are here for reference but we encourage you to refer to ____ instead if it isn't.

[meganesu]

Thanks for the ideas! It's definitely a challenging problem, especially since some of the orphaned docs are up to date and some of them aren't. We do want to keep improving the docs site, so this will be a good thing for us to add to our roadmap in the future.