[docs] (meta) Incrementally improve top 25 learning workflows with baseline evaluations

[prestonso]

A meta issue to track incremental improvements to documentation captured in baseline evaluations of the top 25 workflows.

You can participate in this initiative too! See below for information about contributing.

Summary

Thanks to @marcysutton and @jlengstorf in their enumeration of the top 25 workflows that Gatsby developers seek out in documentation, we have a robust understanding of the most common needs for those using Gatsby on a day-to-day basis.

This meta issue is intended to provide a list of constituent issues targeting those top 25 workflows and the improvements based on those evaluations.

Contributions welcome! Please keep reading for evaluation criteria that we are applying to all of these learning workflows as well as an enumeration of the top 25 workflows and corresponding existing issues.

Relevant information

Evaluation criteria

There are six areas by which we are evaluating the top 25 learning workflows:

Criterion	😞	😐	😄
Searchability	5th page of results or nonexistent	2nd–4th page of Google results	1st page of Google results
Discoverability	Within 6+ clicks on .org (or trapped in GH issue)	Within 4-5 clicks on .org	Within 2-3 clicks on .org
Completeness	Entire procedures missing (6+ clicks required)	Some steps missing (4-5 clicks required)	Docs mostly or fully complete (no more than 2-3 clicks)
Linkedness	No links to other useful docs pages	Some links to other useful docs pages	Many links to other useful docs pages
Tone and accessibility (for tutorials and guides)	Negative or overbearing tone	Neutral tone	Friendly and helpful tone
Tone and accessibility (for docs and API pages)	Uninformative, list of prerequisites absent	Somewhat informative, prerequisites are somewhat incomplete	Informative, prerequisites are clear
Style	Many style issues (needs proofread)	Some style issues (e.g. capitalization)	Adheres fully to style guide

NB: All recommendations are prefixed with [rec] and collated later in each workflow evaluation.

List of workflows

If an issue does not exist for a workflow (except where [skip] is indicated), create an issue for that workflow and link from it to this meta issue (see template below). Prefix the workflow below with the issue number. Boxes should only be checked once a pull request is merged in that addresses the improvements identified by the evaluation.

• 1. [docs] [workflows] Improve docs for setting up a blog that pulls content from Markdown #13710: Setting up a blog that pulls content from Markdown
• 2. [skip]: Setting up Gatsby Preview with Contentful [gatsbyjs.com]
• 3. [docs] [workflows] Improve docs for linking to Gatsby and non-Gatsby content #13712: Linking to Gatsby and non-Gatsby content (merged in chore(docs): Improve linking and starters workflows #14036)
• 4. [docs] [workflows] Improve docs for using starters #13715: Using starters (merged in chore(docs): Improve linking and starters workflows #14036)
• 5. [docs] [workflows] Working with images #14529: Working with images and videos (partially addressed in fix(docs): improve Gatsby Image docs #13170 and fix(docs): improve image docs from workflow evaluation #14697, see also [docs] document component for HTML5 videos #3346 (comment))
• 6. docs(www): 25 Workflows - Finding a Source Plugin #14846 14796: Finding a source plugin
• 7. [docs] [workflows] Improve docs for setting up a blog that pulls content from WordPress #13876: Installing and using WordPress
• 8. [docs][workflows] Adding and organizing CSS (including Sass) #14635: Adding and organizing CSS (including Sass)
• 9. [docs] [workflows] Using Gatsby Themes #18242 Using Gatsby Themes
• 10. [docs] [workflows] Embedding components in Markdown with MDX #14258: Embedding components in Markdown with MDX
• 11. [docs][workflows] using GraphQL in Gatsby #16981 Working with GraphQL
• 12. [docs][workflows] building apps with Gatsby #18993 Building Apps with Gatsby
• 13. [docs] [workflows] Building for E-commerce #19768 Building for E-commerce
• 14. docs: guide on troubleshooting common errors #19966 Troubleshooting error messages from queries not working
• 15. Using Schema Customization
• 16. [docs][workflows] plugin authoring workflow improvements #20232 Building Plugins and Themes
• 17. [docs] [workflows] Deploying to Netlify #13804: Deploying to Netlify
• 18. [docs] [workflows] Improve docs for "Working with fonts and typography" #17703: Working with fonts and typography
• 19. [docs][workflows] Deploying to other hosting services #20691: Deploying to other hosting services
• 20. feat(docs): adding an RSS Feed #11941: Adding an RSS feed
• 21. [docs][workflows] Working with Style Libraries and Components #21278 Working with style libraries and components
• 22. Implementing search with Algolia
• 23. [docs] [workflows] Implementing Google Amp #17645: Implementing Google AMP
• 24. Adding a contact form (Doc added: docs(www): add Build a Contact Form reference guide (#14564) #14768)
• 25. npm vs. yarn

Contributing

To contribute, create a new issue titled "[docs] [workflows] Name of workflow being evaluated" and copy the template below for the text. See #13710 for a reference example.

While conducting evaluations, ignore all existing knowledge of and expertise with Gatsby, and imagine yourself in the position of a novice Gatsby user.

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 [describe workflow as completely as possible].

# Evaluation

[Change emoji below based on your evaluation.]

| Search | Discover | Complete | Linked | Tone | Style | Overall |
| --- | --- | --- | --- | --- | --- | --- |
| 😐 | 😐 | 😐 | 😐 | 😐 | 😐 | 😐 |

# Steps taken to implement

[List out steps taken to implement the workflow, evaluating against each of the criteria in the process.]

# Recommendations

- [ ] [List recommendations during evaluation here to be picked up in a pull request. This issue may be closed when all recommendations are implemented or deprioritized.]

Acknowledgments

Thank you to @marcysutton, @shannonbux, and @marisamorby for their feedback during this process and to @marcysutton and @jlengstorf for the foundational work of identifying these learning workflows.

[prestonso]

Added "help wanted" label as this is a great way for new contributors to begin contributing to Gatsby documentation.

[prestonso]

Added a link to #13804 in the meta — thanks for your help, @aravindballa!

[shannonbux]

This looks excellent! I think part of the steps that will be crucial to document are how people searched for docs related to each workflow.

…

On Mon, Apr 29, 2019 at 6:11 AM Preston So ***@***.***> wrote: A meta issue to track incremental improvements to documentation captured in baseline evaluations of the top 25 workflows <https://docs.google.com/spreadsheets/d/175iZyC8khLy1JQncvgyvAD_vXpfsHxswQcn6N7GDeRA/edit> . You can participate in this initiative too! See below for information about contributing. Summary Thanks to @marcysutton <https://github.com/marcysutton> and @jlengstorf <https://github.com/jlengstorf> in their enumeration of the top 25 workflows <https://docs.google.com/spreadsheets/d/175iZyC8khLy1JQncvgyvAD_vXpfsHxswQcn6N7GDeRA/edit> that Gatsby developers seek out in documentation, we have a robust understanding of the most common needs for those using Gatsby on a day-to-day basis. This meta issue is intended to provide a list of constituent issues targeting those top 25 workflows and the improvements based on those evaluations. Contributions welcome! Please keep reading for evaluation criteria that we are applying to all of these learning workflows as well as an enumeration of the top 25 workflows and corresponding existing issues. Relevant information Evaluation criteria There are six areas by which we are evaluating the top 25 learning workflows: Criterion 😞 😐 😄 *Searchability* 5th page of results or nonexistent 2nd–4th page of Google results 1st page of Google results *Discoverability* Within 6+ clicks on .org (or trapped in GH issue) Within 4-5 clicks on .org Within 2-3 clicks on .org *Completeness* Entire procedures missing (6+ clicks required) Some steps missing (4-5 clicks required) Docs mostly or fully complete (no more than 2-3 clicks) *Linkedness* No links to other useful docs pages Some links to other useful docs pages Many links to other useful docs pages *Tone and accessibility* (for tutorials and guides) Negative or overbearing tone Neutral tone Friendly and helpful tone *Tone and accessibility* (for docs and API pages) Uninformative, list of prerequisites absent Somewhat informative, prerequisites are somewhat incomplete Informative, prerequisites are clear *Style* Many style issues (needs proofread) Some style issues (e.g. capitalization) Adheres fully to style guide <https://www.gatsbyjs.org/contributing/gatsby-style-guide/> NB: All recommendations are prefixed with *[rec]* and collated later in each workflow evaluation. List of workflows 1. Setting up a blog that pulls content from Markdown 2. Setting up Gatsby Preview with Contentful [gatsbyjs.com] 3. Linking to Gatsby and non-Gatsby content 4. Using starters 5. Working with images and videos 6. Finding a source plugin 7. Installing and using WordPress 8. Adding and organizing CSS (including Sass) 9. Using Gatsby themes 10. Embedding components in Markdown with MDX 11. Using the GraphQL explorer to understand your source data 12. Troubleshooting error messages from queries not working 13. Installing and using Contentful 14. Deploying to Netlify 15. Working with fonts and typography 16. Deploying to other hosting services 17. Adding an RSS feed 18. Making reusable components 19. Implementing search with Algolia Contributing To contribute, create a new issue titled "[docs] [workflows] Name of workflow being evaluated" and copy the template below for the text. See (issue link forthcoming) for a reference example. **User story:** As a new Gatsby user, I want to [describe workflow as completely as possible]. Search Discover Complete Linked Tone Style Overall 😐 😐 😐 😐 😐 😐 😐 *Steps taken to implement:* [List out steps taken to implement the workflow, evaluating against each of the criteria in the process.] Acknowledgments Thank you to @marcysutton <https://github.com/marcysutton>, @shannonbux <https://github.com/shannonbux>, and @marisamorby <https://github.com/marisamorby> for their feedback during this process and to @marcysutton <https://github.com/marcysutton> and @jlengstorf <https://github.com/jlengstorf> for the foundational work of identifying these learning workflows. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#13708>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AHXWRWSRGDJII3YBUG2SR63PS3XZRANCNFSM4HJDFI4Q> .

[gehtmaguad]

7. Installing and using WordPress and 13. Installing and using Contentful are probably ambiguous. Whats the scope of those workflows? Reading the title it seems unrelated to Gatsby but I think its about how to pull content from those CMS into Gatsby and create a blog/website?

[marcysutton]

@Haezl everything on this list is in relation to Gatsby, so using headless CMS installs to pull in blog/site content. It is sort-of assumed because we're talking about Gatsby workflows

[gehtmaguad]

@marcysutton thanks for clarifying

Added #13876: Installing and using WordPress, looking forward to feedback.

[ghost]

@marcysutton thanks for clarifying

Added #13876: Installing and using WordPress, looking forward to feedback.

I'll be adding an issue for 13. Installing and using Contentful soon

[prestonso]

#13712 and #13715 are both now complete as of merged PR #14036!

[calcsam]

Nice! Note that bullet point 17 was addressed (completed?) with #11941 and bullet point 5 with #13170

[ghost]

Is anyone taking care of using Gatsby theme item? I would like to help with this one.

Hi @leandromuto, I'm assigned to the "Using Themes" workflow! It's under issue #18242. I'll be working on it until at least 10/13. If you have any ideas regarding it, or want to make a PR related to the workflow, feel free to comment on the issue and we can tackle it together 😊

[gillkyle]

I'm going to begin working on no. 12 Building Apps with Gatsby soon, and will have an issue with a workflow assessment that links back to this issue when it's ready.

[sjku1]

Hi, I was thinking of taking on 20. Making reusable components. is it alright if I make an issue for it?

[kylefloros]

I created issue #19768 for
13. Building for E-commerce

[jamstack-elise]

I created issue #20691 for 19. Deploying to other hosting services 😊🖖

[mbappai]

Hey y'all!! Just created an issue #24641 for 22. Implementing Search with Algolia. Waiting for some feedback. Thanks.

PS: First contribution 😄

[ItzaMi]

Hi 👋 I just created the issue #25659 for npm vs. yarn.
Thank you in advance for any feedback!

[pragmaticpat]

@meganesu and @LekoArts - I'm closing this one - it's not received meaningful interaction since July 2020, and our docs have evolved significantly since then.