search

gatsbyjs / gatsby

The best React-based framework with performance, scalability and security built in.
https://www.gatsbyjs.com
MIT License
55.26k stars 10.31k forks source link

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

Closed prestonso closed 3 years ago

prestonso commented 5 years ago

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.

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 commented 5 years ago

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

prestonso commented 5 years ago

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

shannonbux commented 5 years ago

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 notifications@github.com 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 https://github.com/gatsbyjs/gatsby/issues/13708, or mute the thread https://github.com/notifications/unsubscribe-auth/AHXWRWSRGDJII3YBUG2SR63PS3XZRANCNFSM4HJDFI4Q .

gehtmaguad commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

@marcysutton thanks for clarifying

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

ghost commented 5 years ago

@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 commented 5 years ago

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

calcsam commented 5 years ago

Nice! Note that bullet point 17 was addressed (completed?) with https://github.com/gatsbyjs/gatsby/pull/11941/ and bullet point 5 with https://github.com/gatsbyjs/gatsby/pull/13170

jlengstorf commented 5 years ago

@calcsam thanks! I edited the original issue to reflect that.

prestonso commented 5 years ago

@jlengstorf I don't know if #13170 covers video handling — if not, should that be separated out into another workflow?

jlengstorf commented 5 years ago

@prestonso great question — I think @marcysutton already did a bunch of work on the video workflows, though. Maybe she can add more info here?

marcysutton commented 5 years ago

Hey there. #13170 did add more docs for working with video, but it doesn't quite go all the way for HTML5 video. The page has a callout for requesting more details and there's an open issue:

jlengstorf commented 5 years ago

Thanks @marcysutton! I updated the issue to reflect that and unchecked the video workflow todo.

gillkyle commented 5 years ago

Just began work on:

  1. Embedding components in Markdown with MDX

over in #14258.

jlengstorf commented 5 years ago

@gillkyle thanks! Feel free to edit this issue to add the reference to the checklist above!

marcysutton commented 5 years ago

I'm taking on the image workflow! Initial evaluation here: https://github.com/gatsbyjs/gatsby/issues/14529

gatsbot[bot] commented 5 years ago

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contributefor more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

brolag commented 5 years ago

Taking Google AMP implementation https://github.com/gatsbyjs/gatsby/issues/17645

jonniebigodes commented 5 years ago

Go for it, can't wait to see it, been tracking the amp integration wirh Gatsby.

leandromuto commented 5 years ago

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

marcysutton commented 5 years ago

@leandromuto yes -- that one is being discussed right now internally. If anything changes though, I'll get in touch with you. Thanks for offering!

leandromuto commented 5 years ago

@marcysutton can you provide an updated list of the topics that are not being discussed? Thanks!

nicholaspung commented 5 years ago

If no one is taking "Working on fonts and typography", I've created an issue for it and would like to work on it! #17703

marcysutton commented 5 years ago

@leandromuto this is the most up-to-date list: I've updated it with some of the assignments and work that started recently.

@nicholaspung sounds great! We've recently added some recipes for working with fonts, but I think there could be a whole reference guide on it, in addition to the Typography.js library doc.

leonardodino commented 5 years ago

@marcysutton I think you meant @leandromuto 🙂

LekoArts commented 5 years ago

@bvlktech Please don't unpin the pinned issues. Thanks!

ghost commented 5 years ago

@LekoArts oh snap im sorry i thought that that was just on my end not everyones im sorry 🤦‍♀️ wont happen again my mistake

ghost commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

kylefloros commented 4 years ago

I created issue #19768 for

  1. Building for E-commerce
jamstack-elise commented 4 years ago

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

mbappai commented 4 years ago

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

PS: First contribution 😄

ItzaMi commented 4 years ago

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

pragmaticpat commented 3 years ago

@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.