Added three new sections to the docs #7121
Conversation
The "Testing" section already has a few PRs about to be merged. Will need to make stub articles for the "Sourcing content and data" section and the "Adding third-party services" section. @calcsam I don't know if I did the "Headless CMS" section inside the "Sourcing content and data" section correctly. Also, this process is giving me pause on how many levels of infinite nesting is reasonable. There is a point at which we'd need to actually create a whole new page for a set of docs if it has enough children with grand-children and great-great-grand-children, etc!
shannonbux
added
the
type: documentation
|
@KyleAMathews looping you in here too |
|
Deploy preview for gatsbyjs failed. Built with commit 6ecd97c https://app.netlify.com/sites/gatsbyjs/deploys/5b6c995c02ed8373d953cd62 |
|
Deploy preview for using-postcss-sass failed. Built with commit 6ecd97c https://app.netlify.com/sites/using-postcss-sass/deploys/5b6c995d02ed8373d953cd6a |
|
Deploy preview for using-drupal ready! Built with commit 6ecd97c |
|
Deploy preview for image-processing failed. Built with commit 6a01ea8 https://app.netlify.com/sites/image-processing/deploys/5b69dca4c6aed671bd1dd189 |
|
Deploy preview for using-glamor failed. Built with commit 6a01ea8 https://app.netlify.com/sites/using-glamor/deploys/5b69dca4c6aed671bd1dd18c |
|
Deploy preview for gatsbygram ready! Built with commit 6ecd97c |
|
Deploy preview for using-jss failed. Built with commit 6a01ea8 https://app.netlify.com/sites/using-jss/deploys/5b69dca7c6aed671bd1dd1aa |
|
Deploy preview for using-styled-components failed. Built with commit 6a01ea8 https://app.netlify.com/sites/using-styled-components/deploys/5b69dca4c6aed671bd1dd18f |
www/src/data/sidebars/doc-links.yaml
Outdated
| link: /docs/filesystem/ | ||
| - title: Database* | ||
| link: /docs/database/ | ||
| - title: SaaS service* |
www/src/data/sidebars/doc-links.yaml
Outdated
| link: /docs/prose/ | ||
| - title: Filesystem* | ||
| link: /docs/filesystem/ | ||
| - title: Database* |
www/src/data/sidebars/doc-links.yaml
Outdated
| link: /docs/contentful/ | ||
| - title: Prose* | ||
| link: /docs/prose/ | ||
| - title: Filesystem* |
There was a problem hiding this comment.
Do you have a strong opinion on link title? Thinking eg "From the filesystem" might be good, etc. Slug should be something that stands alone, eg /docs/sourcing-from-the-filesystem/ -- /docs/filesystem is a bit confusing.
There was a problem hiding this comment.
& other slugs should probably be changed as well
There was a problem hiding this comment.
I was trying shorter ones because long ones look funny in the sidebar! The URL is important too. I'll try your suggestion and we can see how it looks
www/src/data/sidebars/doc-links.yaml
Outdated
| link: /docs/adding-third-party-services/ | ||
| items: | ||
| - title: Search* | ||
| link: /docs/search/ |
There was a problem hiding this comment.
More descriptive slugs? eg adding-search, adding-forms, adding-analytics?
www/src/data/sidebars/doc-links.yaml
Outdated
| @@ -83,19 +83,30 @@ | |||
| link: /docs/programmatically-create-pages-from-data/ | |||
| - title: Querying data with StaticQuery | |||
| link: /docs/static-query/ | |||
| - title: Headless CMS* | |||
| link: /docs/headless-cms/ | |||
| - title: Sourcing content and data* | |||
There was a problem hiding this comment.
This whole section should be moved before the "Querying Data" section. We should be putting these sections in the order the user would be doing them, similar to the order in https://www.gatsbyjs.com/integrations/ or https://www.gatsbyjs.com/how-it-works/
There was a problem hiding this comment.
(this could be done in a separate PR as well, obviously there's more re-ordering)
There was a problem hiding this comment.
Ok! @KyleAMathews initially helped put these in order, so we'll need to sync up about this!
There was a problem hiding this comment.
oh wait, I was looking at the wrong section header for this comment. So, because Headless CMSs is within this category, wouldn't someone need to know how to query with GraphQL first before reading about Headless CMSs?
There was a problem hiding this comment.
It's not a big deal one way or the other but I agree with Sam here that someone new to Gatsby would first want to read a bit about how you can source data from anywhere before they move onto using graphql to pull that data into their components.
|
Left some comments -- thanks @shannonbux! |
|
Re: Layers, right now we're at 4, which feels about right at the moment. I wouldn't go any deeper, but it feels like we need all of these layers, eg it's difficult to see how we would get rid of any of these layers: Guides > Sourcing Content and Data > Headless CMS > Contentful |
|
Thanks @calcsam! I'll address your feedback right now and re: 4 layers, I agree we shouldn't go any deeper, and even this layer might look strange. I decided to give it a go and then look at the deploy preview to see if it functions ok (sometimes longer titles look funny in the sidebar). If we start feeling the need to go to 4 or 5 layers in a certain section so it's kind of "busting at the seams," we'll have to evaluate whether we need a dedicated page for that particular section. Even though the new hierarchy fits a lot more, it might not fit everything... |
* Added three new sections to the docs The "Testing" section already has a few PRs about to be merged. Will need to make stub articles for the "Sourcing content and data" section and the "Adding third-party services" section. @calcsam I don't know if I did the "Headless CMS" section inside the "Sourcing content and data" section correctly. Also, this process is giving me pause on how many levels of infinite nesting is reasonable. There is a point at which we'd need to actually create a whole new page for a set of docs if it has enough children with grand-children and great-great-grand-children, etc! * Addressed Sam's feedback * updated sections
The "Testing" section already has a few PRs about to be merged.
#6708
#6678
Will need to make stub articles for the "Sourcing content and data" section and the "Adding third-party services" section.
@calcsam I don't know if I did the "Headless CMS" section inside the "Sourcing content and data" section correctly. Also, this process is giving me pause on how many levels of infinite nesting is reasonable. There is a point at which we'd need to actually create a whole new page for a set of docs if it has enough children with grand-children and great-great-grand-children, etc!