docs: reorganize query docs #735

alexkrolick · 2021-01-13T02:49:35Z

give queries a top-level nav entry instead of
nesting under DOM Testing Library
give each query its own page
reorganize pages like "Which Query" under the new heading
add some pointers to related APIs that users will need after querying
- Improving and Diversifying the Testing Library Recipes #734, Unify "Async utilities" page #489, Unify "Firing Events" page #490, Emphasize most common uses of fireEvent #469
minor content tweaks and formatting fixes
update internal links and redirects

Closes #485

- give queries a top-level nav entry instead of nesting under DOM Testing Library - give each query its own page - reorganize pages like "Which Query" under the new heading - update internal links and redirects

alexkrolick · 2021-01-13T03:07:57Z

docs/queries/about.mdx

@@ -0,0 +1,418 @@
+---


This and the other pages in the queries folder are the main changes in this PR

kentcdodds

I'm a big fan of this improvement 👍

eps1lon

Really appreciated that!

give queries a top-level nav entry instead of
nesting under DOM Testing Library

I expected it to appear in the left sidebar and it took me some time to find the new link. What does everyone think about moving it to the left sidebar?

Frameworks > DOM Testing Library > Queries now just lists a single link to /docs/queries/about/. Would it be simpler to redirect from /docs/dom-testing-library/api-queries to /docs/queries/about/ and remove internal usage of /docs/dom-testing-library/api-queries?

docs/dom-testing-library/api-async.mdx

docs/queries/about.mdx

MatanBobi · 2021-01-13T07:07:58Z

I really like this change.
I agree with @eps1lon that we're used to finding these at the left sidebar but I think it's helpful to have it at a top level.
We also wanted to unify the async utilities and the firing events sections.
I'm trying to see if this solution is scalable or maybe we need to create a more generic title?

Co-authored-by: Sebastian Silbermann <[email protected]>

docs/dom-testing-library/api-async.mdx

Co-authored-by: Adrià Fontcuberta <[email protected]>

afontcu

This looks great 🎉

docs/dom-testing-library/api-async.mdx

afontcu · 2021-01-13T07:35:40Z

docs/dom-testing-library/api-helpers.mdx

-const { getByText } = within(document.getElementById('messages'))
-const helloMessage = getByText('hello')
+const messages = document.getElementById('messages')
+const helloMessage = within(messages).getByText('hello')


way more clear 👌

Co-authored-by: Adrià Fontcuberta <[email protected]>

alexkrolick · 2021-01-13T07:42:10Z

remove internal usage of /docs/dom-testing-library/api-queries

I think I got rid of these, but left the page in the DOM TL tree so that it would at least contain the full API if you are browsing library docs directly. It might make sense to add some more text later that explains the relationship between the core APIs, DOM Testlng Lib, and framework wrappers.

should this go in the sidebar?

One thing I like about giving it its own section is that we can keep the nav list expanded on page load. I could see "Core API" or just "API" being the title, in order to make room for an "interactions" (events) section, but I think the top nav having both "Docs" and "API" would be confusing

what if we add async and events sections?

I have been thinking we basically need all the concepts from my talk here https://www.youtube.com/watch?v=b8SOFNc_X_A pulled into a docs page. On top of that, we should give all of the top-level APIs the same treatment as the Queries, so you can browse most of them at a glance from the left nav rather than clicking into pages.

alexkrolick · 2021-01-13T08:24:46Z

How does this look? I took out the top-nav Queries and moved it to a prominent section in Docs, and moved the event-related pages in the same section. I'd still want to clean up the event stuff later.

eps1lon

Looks great 👍

alexkrolick · 2021-01-13T10:02:12Z

I'm pretty happy with how this brings up some more sections into the top-level and makes it apparent where there are gaps. As @afontcu pointed out, events could use a cleanup. If anyone wants to jump on that soon, feel free.

Merging this iteration now.

MatanBobi · 2021-01-13T10:14:12Z

Looks great, I think that's a really good separation :)

MatanBobi · 2021-01-18T21:56:01Z

@alexkrolick I think that this PR accidentally pushed a yarn.lock file and i18n files that were on the old site..
Am I missing something or we can remove those? :)

alexkrolick · 2021-01-19T19:10:46Z

@MatanBobi you're right, feel free to clean up

alexkrolick requested review from nickserv, afontcu, eps1lon, gnapse, kentcdodds and a team January 13, 2021 02:57

docs: reorganize query docs

dcf41db

- give queries a top-level nav entry instead of nesting under DOM Testing Library - give each query its own page - reorganize pages like "Which Query" under the new heading - update internal links and redirects

alexkrolick force-pushed the reorganize branch from 7043cbb to dcf41db Compare January 13, 2021 02:59

alexkrolick commented Jan 13, 2021

View reviewed changes

kentcdodds approved these changes Jan 13, 2021

View reviewed changes

eps1lon reviewed Jan 13, 2021

View reviewed changes

docs/dom-testing-library/api-async.mdx Outdated Show resolved Hide resolved

docs/queries/about.mdx Show resolved Hide resolved

Update docs/dom-testing-library/api-async.mdx

a344901

Co-authored-by: Sebastian Silbermann <[email protected]>

afontcu reviewed Jan 13, 2021

View reviewed changes

docs/dom-testing-library/api-async.mdx Outdated Show resolved Hide resolved

Update docs/dom-testing-library/api-async.mdx

b95c6e1

Co-authored-by: Adrià Fontcuberta <[email protected]>

afontcu approved these changes Jan 13, 2021

View reviewed changes

Update docs/dom-testing-library/api-async.mdx

bc4fbc0

Co-authored-by: Adrià Fontcuberta <[email protected]>

reorganize event docs

85d5a99

eps1lon approved these changes Jan 13, 2021

View reviewed changes

fix links

38eaa78

alexkrolick merged commit 8e017df into master Jan 13, 2021

nickserv deleted the reorganize branch January 13, 2021 11:02

This was referenced Feb 28, 2021

Unify "Async utilities" page #489

Closed

Unify "Firing Events" page #490

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: reorganize query docs #735

docs: reorganize query docs #735

alexkrolick commented Jan 13, 2021 •

edited

Loading

alexkrolick Jan 13, 2021

kentcdodds left a comment •

edited

Loading

eps1lon left a comment

MatanBobi commented Jan 13, 2021

afontcu left a comment

afontcu Jan 13, 2021

alexkrolick commented Jan 13, 2021

alexkrolick commented Jan 13, 2021 •

edited

Loading

eps1lon left a comment

alexkrolick commented Jan 13, 2021 •

edited

Loading

MatanBobi commented Jan 13, 2021

MatanBobi commented Jan 18, 2021 •

edited

Loading

alexkrolick commented Jan 19, 2021

docs: reorganize query docs #735

docs: reorganize query docs #735

Conversation

alexkrolick commented Jan 13, 2021 • edited Loading

alexkrolick Jan 13, 2021

Choose a reason for hiding this comment

kentcdodds left a comment • edited Loading

Choose a reason for hiding this comment

eps1lon left a comment

Choose a reason for hiding this comment

MatanBobi commented Jan 13, 2021

afontcu left a comment

Choose a reason for hiding this comment

afontcu Jan 13, 2021

Choose a reason for hiding this comment

alexkrolick commented Jan 13, 2021

alexkrolick commented Jan 13, 2021 • edited Loading

eps1lon left a comment

Choose a reason for hiding this comment

alexkrolick commented Jan 13, 2021 • edited Loading

MatanBobi commented Jan 13, 2021

MatanBobi commented Jan 18, 2021 • edited Loading

alexkrolick commented Jan 19, 2021

alexkrolick commented Jan 13, 2021 •

edited

Loading

kentcdodds left a comment •

edited

Loading

alexkrolick commented Jan 13, 2021 •

edited

Loading

alexkrolick commented Jan 13, 2021 •

edited

Loading

MatanBobi commented Jan 18, 2021 •

edited

Loading