[docs] [workflows] Working with images

[marcysutton]

Part of the Top 25 Learning Workflows initiative. See #13708 for the meta issue that this issue falls under.

User story

As a new Gatsby user, I want to work with images on my Gatsby site.

Evaluation

[Change emoji below based on your evaluation.]

Search	Discover	Complete	Linked	Tone	Style	Overall
😐	😄	😞	😄	😞	😐	😐

Steps taken to implement

1. Searchability

   • Searched on Google for "gatsby images", clicked first result https://www.gatsbyjs.org/packages/gatsby-image/
   • Second result on Google is appears to be a better choice but creates the assumption that GraphQL is required to work with images in Gatsby: https://www.gatsbyjs.org/docs/working-with-images/
   • Images, Fonts, and Files reference guide overview will be the best starting point but it isn't on page 1 of Google

2. Discoverability

   • Searched "images" on Gatsbyjs.org, got quite a few results:
     • Images, Files and Video
     • Using Gatsby Image
     • Preoptimizing your Images
     • Working with Images in Gatsby
     • Building a custom, accessible image lightbox
   • Searched "markdown images" and no image-related Reference Guides came up
   • Clickpath on .org
     • Clicked Docs.
     • Clicked Recipes, looked for images. Nothing there.
     • Back to Docs.
     • Clicked Reference Guides.
     • Found Images, Files and Video and subsections.
     • Looked in Gatsby API, no gatsby-image docs.
     • Clicked on Tutorials
     • Nothing for images.
     • Clicked on Advanced Tutorials.
     • Found "Adding Images to a WordPress Site" but nothing general

3. Completeness

   • Images, Files and Video page isn't helpful for discovery if you don't already know the technology.
     • Recommend focusing on workflows over technologies.
     • Add more of a decision tree to help make it clear from the beginning
   • People find the image docs extremely confusing
     • Using queries for images feels like overkill
     • Querying for multiple images like in a photo gallery shouldn't feel such a hack
     • Use cases for importing without GraphQL but still processing?
       • Recommendation: start with better docs for what exists 👍
     • Importing GIFs
     • People have written entire articles about images in gatsby being hard to use
   • Using gatsby-image has two h1's
   • GraphQL parameters are spread across READMEs and docs. Need a clear, scannable/digestible API resource

4. Linkedness

   • Lots of links. That isn't really the problem–it's more the narratives that are and aren't presented, which makes some of the recommendations seem like requirements. With a lack of clear GraphQL API docs it's very confusing to follow.

5. Tone

   • The Gatsby image docs make assumptions about the knowledge of the reader, and require a ton of reading to get the gist.
     • Even senior software engineers have said they are confused by these docs.
     • Recommend to create more of a "Reference" format as opposed to long narrative prose. More headings, bulleted lists, bolded text and callouts may make the text more digestible.

6. Style

   • Some style issues were already fixed in fix(docs): improve Gatsby Image docs #13170

Recommendations

• [-] Add images section to Recipes ([docs] add image docs recipes #14542)
• Look at adding Gatsby Image to API docs (link is there...?)
• [-] Include gatsby-image props, fragments and API info in Reference Guides (N/A, API docs added instead)
• Consider adding "in gatsby" to URL and title of "Images, Files and Video" page to rank higher than the gatsby-image package. Find out why it isn't ranked at all for "gatsby images"
• Add more reference content to Images, Files and Video page to improve learning and decision making
• Closely evaluate "Working with Images in Gatsby" to make it more clear what the page is about, and communicate that GraphQL is not explicitly required
• Add content about working with GIFs
• [-] Add content about working with multiple images ([docs] add info about working with multiple images  #14753)
• [-] Incorporate a gatsby-image tutorial (Tutorial: add gatsby-image #9374)

[marcysutton]

@KyleAMathews out of curiosity, could gatsby-image bundle gatsby-transformer-sharp and gatsby-plugin-sharp? Seems like that would simplify things a bit.

[marcysutton]

Notes from Kyle in Slack:

With plugins soon being able to have their own gatsby-config.js, a single plugin could set this up

e.g. gatsby-fs-image could have an interface in gatsby-config.js like:

resolve: `gatsby-fs-image`,
options: {
  imageDirectory: `src/images` // relative to root of site
}

// in a component
import { Img } from "gatsby-fs-image"

<Img src="apple.jpg" width={200} />

@sidharthachatterjee this would need static query args working too

[marcysutton]

All outstanding items are open as separate issues, so with #14697 merged this item can be closed. There are still more improvements to make, but we can focus on the smaller pieces! We're always open to further suggestions and fixes, as well.