Reorganize docs?

[pedroapfilho]

I know that we use Docusaurus, but as the list of different documentations grows, it's hard to keep adding new items here, and separate the documentation as it has to be.

I thought about we create a Gatsby Theme for it, one with all the correct parts for each different library, more focused on the lib itself, and not in a general way (as a React developer, I don't need to see the Vue testing-library, and vice-versa).

I would be happy to create the first POC.

[kentcdodds]

What do you think @alexkrolick?

[alexkrolick]

I don't want to maintain a Gatsby site, Docusaurus works pretty well for everything we need

[alexkrolick]

Open to discussing a better organizational scheme though, as it seems this question isn't really about Gatsby per-se but the overall hierarchy and overlap between the libraries

[afontcu]

Open to discussing a better organizational scheme though

This is something I feel should be discussed at some point. Docs have grown organically as we've been adding features, and they could use some redesign. For instance, all common queries from DTL could (should?) have a single source of truth, and so on.

I agree, thou, that Docusaurus could still fit our needs.

anyway, my two cents :)

[pedroapfilho]

Alright about Docusaurus, I saw some nice features there.

But I think we could reorganize the docs, make them more "assertive".

[sarahdayan]

Hi there! I've been using Testing Library with React and Preact for about six months, which has allowed me to use the documentation extensively. The library is fantastic, but I think the documentation isn't always helpful.

Here's a non-exhaustive summary of what I've observed when using the docs:

Multi-flavor website

As @pedroapfilho said, when you're using the library for React, you don't need to see the Vue documentation and vice versa. All flavors are consolidated under a single website (except for React Native), which makes the sidebar busy, and the search a lot less useful than it could be. I often find myself searching and ending up on different flavors, which isn't a satisfying experience.

If you want to keep all flavors under a single website, there needs to be a better split, so you don't see things you don't want, and you remain in your "space". It's mostly UI work. Also, it requires more flexibility with the search so you don't accidentally end up on a section of the docs that you don't want (there's probably something to sort out for this by tweaking the DocSearch configuration).

If you want to split the docs into several websites, then it's going to be a lot easier to keep things focused. There will be new constraints. For example, it might require separate DocSearch instances (there might be something we can do to provide more flexibility with a single instance, though). Also, it would need the necessary structure to repeat shared content across all websites without duplicating content (as you mentioned @afontcu, this is an important topic).

Both solutions are viable. The first one requires more UI work, the second one more infra.

Common vs. dedicated content

There's content that applies for every flavor (such as queries, events, async utilities, or helpers) and content that's flavor-specific. Still, it's hard to tell them apart because the former is documented under DOM Testing Library. I understand that DTL is the mother library upon which all other libraries rely, but that's something one may not fully realize right away. Also, for better developer experience, you don't want the cognitive overhead of having to understand that. Testing can be a stressful topic, so making things extra clear without asking people to figure too much on their own can reduce frustration.

I don't know what Docusaurus offers, but storing common data and displaying it wherever you want could be helpful. It would allow for a single source of truth, but also document it wherever needed, and repeat it if necessary. I worked with Middleman for a while, which provided a YAML-based data file mechanism. That was quite handy.

Documentation

Right now, the documentation is very API-oriented. While API references are useful, it makes the documentation centered on Testing Library rather than on the user and their needs. Having a more guide or solutions-oriented structure, in addition to the API reference, would be extremely helpful for people to get started. There are many use cases that one can encounter, but 90% of the time, we're all doing the same things. Having documented how-to guides with code examples for given situations (e.g., How to test keyboard shortcuts, Testing a custom <select> component) is helpful. It keeps people from reinventing the wheel.

Additionally, it could be nice to have a Best practices section. Kent often writes blog posts, tweets, or GitHub replies on these topics that get scattered across the Internet, and it's tough to find what you need. Having a canonical place for these would be helpful.

Thanks again for the excellent work! I would be more than happy to give a hand if you want to dig more on those topics 🙂

[kentcdodds]

I'm a huge fan of making the documentation better and less confusing. I totally understand that it is a little disorganized and could be improved.

Unfortunately I don't personally have bandwidth to work on this, but I'm happy to enable anyone who wants to give it a go. I'll give commit access to anyone who makes a solid PR or helps in reviewing PRs that make improvements to the docs in this way.

[alexkrolick]

• I think it would be good to do this as part of exploring a monorepo for the packages, to make it easier to update downstream packages and docs all at the same time. I don’t think fragmenting further by site will be very nice to maintain
• Search probably won’t be that simple since it’s one big index across all the md files, but it’s worth looking into
• Docusaurus v2 has MDX support which might be a good way to build some sort of language widget for the query docs. The main reason these are repeated now is because the bound queries take 1 less argument than the base DTL ones.

[kentcdodds]

On that last point, I don't think we need to document the base queries as much. And I don't think we need to document the bound queries much either. Let's just document screen and then it's much easier. At that point, the only difference between the libraries is the way you get stuff on the screen.

[afontcu]

Hi @sarahdayan! Thanks for the feedback ❤️ I'm up for some docs revamping!

To recap a bit; can we build this in an incremental fashion? I don't have the bandwidth to work on a full revamp for docs either, but I feel there are several low-hanging fruit that we could tackle:

• Unify "Queries" pages.
• Collect "Best Practices". For the time being, it could be a list of posts/resources that the Testing Library shares as The Proper Way™️ of using the library.
• Reduce the duplication of each framework by talking only about the specificities of them. For instance, VTL requires you to await fireEvent. Any other stuff related stuff should point to the "main" Fire Event page.
• Reduce the prominence of DTL in favor of each framework.

Other (potentially more demanding) stuff:

• Add small guides on common scenarios (say, HTTP requests, keyboard shortcuts, custom select components… you name it).
• Move to a monorepo where code and docs live together.

Any other ides? 🙌

[pedroapfilho]

I'm loving this thread ❤️

Here it goes some ideas:

• We could implement the search with Algolia (https://www.algolia.com/for-open-source/)
• We should migrate to Docusaurus v2, the benefit is significant, and the work is not that big of a deal for us (https://v2.docusaurus.io/docs/migrating-from-v1-to-v2)
• We could create an easy way to collect best practices.

[sarahdayan]

@pedroapfilho You're already using Algolia DocSearch, and applying for AOS will probably get you redirected to DocSearch (which is the go-to for open source docs). If there's any limitation with DocSearch that you've experienced let me know, I can definitely help!

@afontcu Definitely would love to help incrementally, a full revamp is probably impossible as we all have busy lives 🙂 Your action points are great. Any way you want to organize for that? Notion board or just grab and go?

[MatanBobi]

Regarding the migration of Docusaurus to v2, It looks like V2 is in alpha for a lot of time now and is stated as stable so I think this can be a good step to start implementing it.
Another thing, there's an open issue about this migration specifically so I'll just reference it here (#360).

About monorepo, I believe that moving to a monorepo would benefit but will definitely be more demanding than the other tasks.

I'm up for some docs work or monorepo work if any help is needed :)