Improve gatsby-image docs

[shannonbux]

Summary

There are several docs about how to use images in Gatsby and there is some confusion about what best practices are.

Here is a list of the docs that need to be edited to be clear and consistent:
https://www.gatsbyjs.org/docs/working-with-images/
https://www.gatsbyjs.org/docs/using-gatsby-image/
https://www.gatsbyjs.org/docs/adding-images-fonts-files/
https://www.gatsbyjs.org/packages/gatsby-image/?=gatsby-image

Motivation

People get confused about when and how to use gatsby-image. Here are some notes from an interviewee about their struggles with gatsby-image docs if this helps

"
no mention of css background images. there is discussion of how Img replaces img but would be great to also address if this can be used for css bg image.

no mention of which props are mandatory or optional

also, the props section... is it meant to be nested under the "sizes" queries section? or does it apply to resolutions too?

in the example codebase, there seems to be a lot of "noise". for example remove all unnecessary css. no need for utils folder. need to really isolate the core teachings and learnings here.

theres no comments in the code. im forced to hack thru it

remove all the lorem text. that actually makes things super confusing. instead replace it with text explaining what is exactly happening. even me, a native english speaker, spent a moment or two trying to figure what the heck the text was referring to

https://www.gatsbyjs.org/packages/gatsby-image/#some-other-stuff-to-be-aware-of
this makes no sense. this needs a "why". why would someone want to set display none in this specific context. maybe its my own ignorance but from what i can tell, its because you want to load different images for different viewports? if thats the case, then state it! "if you want to load a different image for a different viewport then you will likely use the display none property. this means you will also.... etc"

https://www.gatsbyjs.org/packages/gatsby-image/
please link to the example page.

https://www.gatsbyjs.org/packages/gatsby-image/#two-types-of-responsive-images
this section seems contradictory. why cant i have both? what if i want retina images but also want those images to stretch across a fluid container. also, are we sure we are using the term "thumbnail" correctly? i usually associate that with a small image.

https://www.gatsbyjs.org/packages/gatsby-image/#resolutions-queries
where's the full API?

is gatsby-image dependent on gatsby-transformer-sharp? that is, do i need to yarn add both? if so, why dont you simply roll up sharp into image?

and when i look at the using-gatsby-image example, i see no mention of gatsby-image in the gatsby-config file

and then when i look at https://image-processing.gatsbyjs.org/ its hard for me to understand why we need two example websites. they config looks similar enough and they both seem to implement gatsby-image in the same way.
"

@benjaminhoffman thanks for contributing to this!!

[danielberndt]

One thing that took me quite some time to understand is the sizes property of fluid images. My use case was to create fluid-size images that take up one third of the screen. By default, gatsby assumes that fluid images take up all the available screen width and therefore it loads images that are way too big.
This comment helped me understand how to overwrite the default behaviour and I think it might make sense to describe in the docs how to set up non-full-screen-width images :)

[gatsbot]

Old issues will be closed after 30 days of inactivity. This issue has been quiet for 20 days and is being marked as stale. Reply here or add the label "not stale" to keep this issue open!

[gatsbot]

Hey again!

It’s been 30 days since anything happened on this issue, so our friendly neighborhood robot (that’s me!) is going to close it.

Please keep in mind that I’m only a robot, so if I’ve closed this issue in error, I’m HUMAN_EMOTION_SORRY. Please feel free to reopen this issue or create a new one if you need anything else.

Thanks again for being part of the Gatsby community!

[marcysutton]

There have been some changes made to the Gatsby Image docs, but overall this issue was closed without resolution and there is still room for improvement. Some very helpful feedback from @calcsam in the Video & Media docs PR (#12906):

• The "Adding Images, Fonts, and Files" page is confusing. It drops you right into the middle of things. It needs an introduction, something along the lines of "There are two ways to import assets, such as images, fonts, and files, into a Gatsby site. The default path is import the file directly. The alternative path, which makes sense for some edge cases, is to use the static folder."
• A lot of the content in the "Adding Images, Fonts, and Files" file is duplicated in "Static Pages." I wonder if we should either (1) pull out most of the content here into an additional page called eg "Importing assets directly into files", and make that page, and the "Static Folder", children of a ~100-word "Adding Images, Fonts, and Files" file -- or (2) push the "Static Folder" content into the "Adding Images, Fonts, and Files" page and eliminate that document.
• The last three sections (Working with Images in Gatsby, Using gatsby-image, and Pre-optimizing your images and are confusingly titled. It's not clear what the relationship between these three pages are. The first two seem to cover much of the same ground. The last one feels like it should be a child of one of the first two, as it covers an edge case.

[gatsbot]

Hey again!

It’s been 30 days since anything happened on this issue, so our friendly neighborhood robot (that’s me!) is going to close it.

Please keep in mind that I’m only a robot, so if I’ve closed this issue in error, I’m HUMAN_EMOTION_SORRY. Please feel free to reopen this issue or create a new one if you need anything else.

Thanks again for being part of the Gatsby community!