[RFC][documentation] What do you think?

[joshuaellis]

Problem

Preface

Whilst I think our documentation coverage is good, I think it can be hard to find what you want. The information architecture of the site isn't quite right. There are pieces of documentation we want to be shouting about e.g. our Imperative API but it's not really doing that.

Going forward

I don't think it's something i'll be able to solve in a day or two, it'll be a classic gradual re-write / shape / tweak. But I welcome contribution either in code or suggestions here. All suggestions will be taken into account, but realistically we can't implement everyone's opinion. It'll be about trying to get the clearest message.

Solution

How can you help?

To get me started, I need to understand the pain points!

• What didn't you like about the documentation?
• What did you find confusing or difficult using the library at first
• What do you like about our documentation compared to others?
• What other documentation sites do you like? (Doesn't have to be animation related)

My own thoughts

For transparency here's a few thoughts i've had:

• We should have an examples page, to show case all of them, they're hiding with the related component!
• Search bar, it's 2021 algolia is a thing, we should get on it!
• The basics are too long, they're not basics if they're that long!

[krispya]

Hi Josh, overall the docs have served me well and only gotten better over time. There are two things that would suggest though:

1. With r3f being mixed with react-spring more often, it makes sense to have an imperative update guide. Maybe this is something I can help with?
2. Spring property controls on the Config page are useful for quickly visualizing spring motion without setting up my own controls. It would be great to enhance this with toggling between visualizing with damping/frequency and tension/friction. Some of us are more used to seeing damping/frequency values. It would also be great to enhance this to visualize with a square moving from one side of the screen to the other. And if we make these enhancements I'd also suggest moving this to its own page section to help people test spring configs.

[trm217]

Let me tell you about my first experience with the react-spring docs.

Around a year ago, I used/tried using react-spring for some micro-interactions in a page that I worked on. I was a bit overwhelmed by the docs at first, so I ended up copying examples onto the page.
Once the example worked, I then tried to adapt the examples to my use case. This worked well for more primitive examples, but this didn't work at all for more complex examples with the useTransition hook.

I specifically remember using this example. Once pasted into my project, the typescript linter went nuts. I had tons of type errors on the arguments passed into the useTransition hook. This felt very frustrating since I couldn't figure out what was wrong and the example was working in the CodeSandBox. Also, the documentation didn't tell anything about the usage with TypeScript.

I believe the following ideas could benefit the documentation:

1. A getting started section. Show how to set up react-spring in your project and how to achieve your first animation with react-spring. Ease the user into using react-spring.
2. Make the API documentation more interactive. When showing a code snippet, that contains working code, show the output of the code next to it, so that one can see what the code does.
3. Split the API docs into sections,
4. Add documentation of how to use an API with typescript. Show what types are accepted with example values. This would've greatly helped me with my troubles. (For example, Next.js has very nice docs on how to use their features with TypeScript. The TS documentation of the api-routes can be found on the bottom of the page)

[looeee]

Hey! So first up let me says it's rare and amazing to see an open source project open up a conversation like this about docs. That already puts you way up in the 0.01% 😁

Regarding the imperative API page in particular - that stood out to me previously, because when I first use react-spring about 6 months ago I read that page, and I had never used a previous version so my reaction was "huh, why are they telling me about deprecated API that I've never seen?". It would be better to open with the current API and then have a final section "Upgrading from the old API".

The actual docs content is pretty good I think, it's been a while since I read it in detail so I won't comment further. There are also many great demos, but they are kind of hidden by being placed at the bottom of each page. What I mean is, if I want to do something, say, create a cool card stack animation:

Then I might remember seeing this demo in the docs somewhere. Right now I would have to remember "hmm, I think I would use useSprings (and not useSpring!) to create that" then go and hunt in that page to find the demo. For something visual like animation that's not intuitive. Maybe you can create a new Recipes page and collect all the demos there?

The final thing I'd say is maybe make the header just a tiny bit smaller. When I click on a new page, with the site in full screen on a 4k monitor, what I see is this:

Don't get me wrong, it's a lovely header. But if I'm in the docs I'm there for info, not pretty graphics. Maybe shrink the header down to 20% vh on all pages except the intro?

[joshuaellis]

Thanks for the feedback folks! I'll be taking a look at all this and hopefully filtering it all in, if you have anyone has additional feedback please continue to post it!

[stoico]

Not crystal clear which Hook applies to which use case. Some of them sound very similar to each other.

[joshuaellis]

Not crystal clear which Hook applies to which use case. Some of them sound very similar to each other.

@stoico would you be able to give an example so I understand better please? ☺️

[stoico]

Preface: I love react-spring and thank you for your work ❤️

Some common scenarios are, say:

1. I have a list and I would like to create a staggered animation
2. I would like to animate a button on hover
3. I would like to animate a side-by-side transition between two tabs (views on the same web app page)

Let's take for example point 1:

• I start by googling 'react-spring docs'
• I land on the homepage
• I read the sidebar to understand which hook is most likely to do the job for my case
• useChain, useSprings and useTrail seem like good candidates in my mind
• I read each of the hooks page one by one and try to figure out which one is the most appropriate in this case
• still sometimes not super clear, so I just end up implementing and trying out one or two, before it clicks for me

Added step:

• Often I resort to also googling say 'react-spring useChain codepens' because from the docs I don't get how it could be fully integrated just by reading the code snippets on there, I get the feeling that something is missing to fully understand how to make everything work in my real codebase

It would be cool if it was possible to structure the Docs the other way around. A list of common animation scenarios and a solution that showcases how to do it. In a sense you could say the docs are backwards, what I am ultimately trying to do is reproduce an animation I have in mind. So, just as an idea to explore, what if the docs were job-to-be-done-centred rather than tech-centered:
Staggered animation for a list? -> "Here's how to do it"
One-off animation on page load? -> "Here's how to do it"
So that I don't even need to figure out which one is the right hook and can't go wrong.

Maybe one more thing: I love the Codepens at the bottom of each page, most of them feel too advanced and an overkill for most situation. They don't provide a gradual learning experience, especially frustrating for First Time users. Adding simpler ones with a single component and one animation would help or where there already are a mix of advanced and simple ones, we could group them in: Easy, Medium, Hard difficulty. So that at each level of the learning journey they user knows immediately which one to investigate. What do you think?

P.S. Interaction wise, I would also recommend making the website header's height a lot smaller everywhere (except the homepage maybe?). Every time I change doc page I need to scroll below the fold. When you're quickly looking up something and browsing lots of different pages to try and find what you need, it adds constant friction.

[jankalfus]

One thing that I would hugely appreciate in the docs would be links to sandboxes with complete code. There are many examples in the docs, but there's seldom code that one could simply copy and paste, and it has many missing parts. For example the "You can transition array" example contains variables like NUM_TRANS with properties on the items such as op or trans which I have no idea what they are, or what should I use in my app in place of those.

[oo0o00oo0]

Hi Josh. Thanks for your work on such a powerful amd fun library!

One thing that I'd like to see is a little more detail into the under-the-hood-ness .

I'm personally someone who likes to know a bit about how things are working behind the scenes, instead if being satisfied with following or copying code. To me react spring is a little bit too black-boxy because as a beginner developer I can't get much out of reading the source.

So I think my suggestion would be just a little more detailed breakdown on how the hooks work under the hood. And perhaps also an explainer to the concept of "rendering outside of react' might be useful.

[Stranger1586]

Hello, Josh.
First off, you did an amazing job building this library, I absolutely adore it.
I will be more than happy to provide some feedback

- What didn't you like about the documentation?

The organization of it.
Here is a few examples:
In the introduction page, you seem to include a quick explanation of springs, that could possibly be expanded into along with some general info about the project.
Imho, those could be split into separate pages.
1- Get started
Should include the portions of the installation instruction (the ones included on the introduction page) merged with parts of the basics page.
2- Why Springs Animations
Move the part where you explain the inner workings of the library there, instead of having it on the introduction page.
3- Testimonials
This is where tweets about the library along with credits to its creators.

- What do you like about our documentation compared to others?

The abundance of examples.
The inclusion of live sandboxes is quite nice.

- What other documentation sites do you like? (Doesn't have to be animation related)

The docs for the framer framework and Vue are pretty good.

[fryerd]

This is great but I'm a PM not a Dev so mainly use these docs to find and reference the Demos which are hidden at bottom of the page.

Then I hospital pass it over to my front-end developer to ask them what's possible to implement when updating/building a new feature.

I would appreciate a nice video introduction or examples of developers actually using react-spring.

It's a lovely library though.

[mohan-ys]

Hi,

I am new to Web Development and to be honest, I could not find what I was looking for.
I have a app with conditional rendering (as can be seen in this video https://youtu.be/5kl1wCBwR_U). I can animate the component entering but I am unable to animate the component exiting & the size change of the container that has these 2 components.

I searched several places & thought 'react-spring' would be a good choice. However, I could not figure out with the documentation available. I thought Transition would be ideal for this since the page (link) has section explicitly for Mount/Unmount single-component reveals. For example what is config={config.molasses} ? I could not find any reference to it. May be it is easy for someone who uses react-spring often but I could not figure it out.

Also, in this video https://www.youtube.com/watch?v=b3G7l7fHRP8 at ~5.30, he shows a webpage with a lot of examples. However, those examples are not available on the official page now.

Please let me know if I am looking at this all wrong. Sorry if I sound harsh, that is not my intention.
For someone who is getting started with react itself, the react-spring documentation may be a up-hill battle. Thanks.