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

[Heilemann]

Please make doc links jump to the content so people don't have to scroll past the giant header (why is it on every page?) every time they navigate.

[asjustis]

Two mentions for improvements, since I just want to start using this and got difficulty already:

1. Add animated under API menu. Had to find it about from this URL https://stackoverflow.com/a/67434651/1935554 (I found it under Basics menu afterwards, but you actually have to read it to find it! ;) )
2. Add a Basic Examples menu to show how to use React Spring for our own components. Pretty much all examples has animated.div, but since I was not familiar with it, felt not sure what to do with it :))

[neolectron]

One "simple" thing to do, to improve the documentation by a factor of two : update all the example to the latest apis with latests standards.
At the moment it is not possible to learn the library based on a exemple and tweak stuff because it is so much outdated and different, that you won't have the same code at home.

Then you will inevitably use/write/improve a "migrate from xx to ^9.0" guide for this task, so it's a good thing aswell.

[maxmezzomo]

I think the docs are quite nice in terms of layout and structure. The library is so flexible which is of course a great thing, so finding what to use and when is not always straight-forward, but I'm new to spring as well, was using framer-motion a lot before. So I think if anything, more examples would be nice because you can always study those and learn more than just reading.

One thing that is ruining a bit the experience with docs is the page scrolling to top every time a link is clicked. This should be a fairly simple thing to fix. The site is Next right so the link prop scroll could be set to false, this could be an issue because then you don't go to the top of the new section, so either the scrolling could be implemented manually, or alternatively the header could just be made less tall.

Thanks for the great work on the lib.

[sammylupt]

First of all, thank you for your great work on the library.

I'm really happy to see this thread! I recently wanted to use React-Spring to recreate the winning animation from Wordle; I had a really hard time.

Example

wordle-animation.mov

Description: 5 boxes; each box bounces up and then bounces back to where it began.

There were broadly two things I struggled with

• How do I model the idea of an animation where the item starts at x, goes to y, and then goes back to x? Is it a loop that happens once? Is there a reverse prop that I have to toggle off? Is it a loop that I let play once, and then it automatically reverses? Do I make an array of values in the “to” value?

• API questions: what is the difference between a hook that is passed a function versus an object? If there is a field called “to”, why is there also a function called to on animated properties? Is the return value is of the hook api, which is a function? Or does it have a property called start, which is a function? Is this a "springs" or a "trail"?

I struggled with the documentation for a few hours and ended up giving up because I couldn't get anywhere close, and none of the examples were helping me get closer.

[joshuaellis]

Sorry to hear you gave up @scottluptowski, you can reach me on Discord in the PMNDRS discord server – JumboJosh.

But I also thank you for taking the time to feedback clearly with some really great questions that you had that I can then reflect on.

To everyone else feeding back, I thank you all ⭐

[kindoflew]

• agree with a smaller header
• maybe we could throw together some walkthroughs/guides for more common or complex use-cases?
• clarification on which hooks are good fits for which use-cases (it probably depends on the project, but a nudge in the right direction could probably be helpful)
• refactor Navigation Pane and Routes:
  • have dropdowns closed by default?
  • rename outdated paths (eg, Render Props)
  • maybe move some sub-paths to top-level (eg, I never noticed the Testing caveats until I was looking through the docs to put this list together)
  • maybe Basics could be a top-level path with different sub-paths to make navigation easier? Although, the flip side of this is that one long page is good for ctrl/cmd-f to search for specific words (like how Svelte does it: https://svelte.dev/docs)

That's all I have for now, I'll try to think of more. And when there is a consensus on direction, I'm more than happy to contribute PRs!

[Heilemann]

+1 for clearer, simple uses cases. With all love, some of the examples are too clever by half, making it hard to clearly understand what's happening.

[varunarora]

Hi Joshua,

I have spent the last two and a half days trying to make react-spring work for my needs. I am really struggling. Like seriously struggling.

I shouldn't be struggling at all. I was among the earliest adopters of React. I have been doing JavaScript stuff for at least 13 years. Things like anime and Motion were a breeze for me.

My biggest fear in writing this comment is it will hurt your feelings. You have put in so much incredible work. The very last thing I want is to make you think your effort is not counting. If I didn't see the promise, I would probably not bother sharing.

So, for a start: your (and your co-contributors') technical skill is incredible! And thank you for showing the humility to ask for feedback.

At this point, I think it is worth reflecting and addressing on the big issues of the moment. React-spring has the foundations of a library as successful in the future as Greensock. But for that to happen, and for another library to not just come in a few months and eat your cake, a lot of things need to change.

Things like:

1. The API is very complicated. It seems like the way the library has been designed, there has been more focus on creating several different models of doing things. In that process, the user isn't often left with one good model of doing things that properly addresses a bunch of scenarios. The different kinds of hook systems are too confusing. If it has taken me more than 2 days to do create a very basic first animation, something is wrong.
2. As you identified correctly, the documentation needs a complete overhaul. No single page is written with a new person in mind. It needs a rewrite with most common use cases in mind. React's documentation is a very good guide in this regard. I think draft-js is pretty good too. I have tens of micro-improvement suggestions here, but in general, lot of work needed. The slow-loading Code Sandboxes make navigating the site and seeing code for demos painful. And cutesies like the massive header are majorly getting in the way of usability of the site. The writing is not easy to sift through. I haven't scratched my head so much in very long.
3. There are no warnings of misuse of the API. Debugging is very difficult.

I have a lot of ideas for solving these issues. All in all, there is a major need for customer-centricity going forward. But putting my ideas in a corner of your issues section or in a channel on your discord feels like the best way for me to spend 5 hours not being useful in any way.

If you would get on a call with me, we could discuss these details and give you a solid pathway forward that is easy to document. Without hearing your concerns to my issues, and without me being able to talk about them by showing you my code snippets, I am afraid I am admitting I wouldn't be able to be very helpful. This stuff can't be communicated in lengthy essays.

Why I am invested: animations w/ React are going to be one of the key pieces of my job in the next year. Choosing the right tooling is not just nice-to-have; it will be critical to our product. I need to use every last feature of the library, given how extensive the use cases for me to address are. After evaluating several options, I ended up wanting to evaluate react-spring and build tooling around this. I am giving it a few more days before I decide on whether this is best path.

Thanks for your work and best wishes. Hope I did not offend you; I only intend to be useful.

[y1n0]

I think it is a little confusing design-wise. whenever I land on the website, I go directly to the first button thinking it would take to a "get started" or some (basics) guide, but instead it take the github discussion page. I think those three CTAs in the hero should be: Get Started, API, and Community or Source if you like.

Also the guides section does not have a starter guide, like a guide to implement basic animated stuff

The Basics Page

The page starts to become confusing from "Do not think of the values you pass as "styles" per se" as the examples used introduce so many parameters that have not been seen before:

  const [flip, set] = useState(false)
  const { x } = useSpring({
    reset: true,
    reverse: flip,
    from: { x: 0 },
    x: 1,
    delay: 200,
    config: config.molasses,
    onRest: () => set(!flip),
  })

What happened to the to keyword? what is config.molasses? what does reset do? reverse, delay, and onReset are kinda self explanatory but why are they attached to a state variable? The user needs to have read the API of useSpring to fully understand this code.. but they are still only in The Basics.

The example could be something quite simple, using the snippets that have been seen before, to point to that we could animate arbitrary keys:

const {fadeAnim} = useSpring({ from: { fadeAnim: 0 }, to: { fadeAnim: 1 } });
return <animated.div style={{opacity: fadeAnim}}>
  I will fade in
</animated.div>

[dragomalefoy]

Notes on this input:

• Demos are mentioned in the beginning of the issue as a wanted feature, I wrote this to highlight the importance of visual examples and clarity.
• This is not a petty-user-complaint, but a suggestion to make information more accessible to
  1. neurodivergent devs/coders/readers struggling with subtext/guessing
  2. fairly new devs/coders/reactlovers
  3. graphic/ux-designers interested in code. All of which apply to me.
• Every react-related documentation threatens readers with lack of clarity and demonstrations, this is not a unique problem. I noticed a pattern of the most notorious non-examplers being libraries with animations and perhaps we can discuss breaking the cycle?

Summary and suggestions:

• Put visual demos of the animations either under Examples or on the top of the current page. Or both, that would rock.
• Don’t link to Codebox, only to send me back to GitHub from there. I will get lost.
• Tell me where to go from the introduction, either written or with demos. If I start to guess, I will get lost.
• The examples on the introduction-page serves no purpose since theyre not explained nor link to the correct doc-page. Either remove them or link them somewhere that’s useful.
• If you want to get an Outstanding on your O.W.Ls, put a tldr of what I can find on the pages at the very top. If I start to scroll down into the underworld, I will get lost.

Now to explaining myself:

Look, I love the hunt, I spend days searching for the perfect anything, components, libraries, CSS-animations, fonts... But when I’ve entered the docs, the hunt is over, and I want to proceed to make things work. Since I have no prior experience with react-spring, I have no idea where to go, because I don’t know what I want to order from the menu presented to me. The flow, or dare I say, reluctant drizzle of the docs looks like this:

1. I don’t even read the introduction, because I don’t want to use anything just yet, I want to see what the possibilities are. If I had, I would have noticed the three demos in the introduction, but their links would have sent me to codebox anyways, without explanation.
2. Instead, I check if there is anything labelled Examples or Demo, but no luck.
3. I begin clicking through categories randomly but don’t see any examples (I scroll like, halfway down, but don’t see anything)
4. By coincidence I find one visual example that’s somewhat far up on the page (configs), and at first, I am convinced that it’s the only animation there is, so I get confused.
5. Open codebox seems like a place where I can find a lot of different examples, so I head there.
6. I try to click on the profile for the codebox but the link leads back to github.
7. Then I notice the Struggling to find things? and go into problem-solving-mode.
8. I scroll all the way to the bottom of every category and there’s the visual examples, to my horror.
9. I write this.

Thank you for caring and asking for feedback, that really stood out to me.
Lots of love <3

[bronsonavila]

I always forget where the Shorthand style props are. It seems like something that should be under API > Common > Props, but it's only under Basics.

Also, it's really a pain seeing the full-page hero every time I change pages in the documentation. Users are basically forced to scroll down the full height of their screen before seeing anything substantive every time they change pages. (I've resorted to just using my ad blocker to hide the hero.)

[dannobytes]

Apologies if this may have been stated in previous comments, but I do have two minor gripes and suggestions:

1. When navigating between different doc pages, the giant (above-the-fold) hero banner section is quite unnecessary for each section. When navigating to a different page, your page jumps back to the top and the banner looks exactly the same everywhere. So it appears like you've not navigated anywhere different until you scroll down to the content. It would be nice to scrap the banner on sub-pages and replace it with a heading that reflects the page you're on.

2. Implementing a quick search (e.g. Cmd+K) would be really helpful to find things.

[iamzapata]

I started using this library recently. It's awesome, thank you!

I was going over the Basics and got stuck for a while in the view interpolation section. I had to re-read it a couple of times before it really made sense, what helped was to concentrate more on the code. Making the Basics content more accessible would be great. I haven't gone over all of the docs, but maybe there are similar issues in other places.

Again, thank you for this library!

[orta]

We got a site update shipped which skips the header on site navigation BTW. I've used these docs quite a bit now, and they're good docs - it's nice work.

When I think about how to structure docs sites (I wrote the sites/docs for TypeScript, CocoaPods and Danger) I try to have three major sections + a REPL:

• A walk through of the whole thing (TypeScript's handbook)
• A set of reference documents which deep dive into specifics ( TS Config page for example )
• A set of tutorials ( I massively downplayed these in TS, because the others were better )
• And a way to teach some of the concepts in a REPL (Playground examples)

What I think would be really useful in learning the basic primitives with react-spring is a concrete showcase of adding animations to an existing app. #1799 (comment) mentioned Wordle, and that might be a simple enough example to start with. For example a tutorial that takes wordle, and incrementally adds animation to the game in key points in a way that echoes how someone would do so in production. That can take you through a few of the APIs, explain some of the nuance and then drop people off at places or examples to dig in further

In terms of a REPL, I think the usage on codesandbox is pretty solid 👍🏻 - maybe there's space for something more tied to your site with sandpack though.

[nguyen-michael]

Is there any way to view v8 API documentation? I couldn't find them any where.

[alimoeeny]

Please put a big link to demos (or examples) at the top of the landing page,
I don't know about others, but the first thing I want from a library is to see what it can do in action,
this is the link https://react-spring.io/hooks/use-spring#demos right?

[iamzapata]

These doc sites are good examples of good documentation:

• https://nextjs.org/docs
• https://vitejs.dev/guide/
• https://vuejs.org/guide/
• https://vitest.dev/guide/
• https://parceljs.org/docs/

[joshuaellis]

These doc sites are good examples of good documentation:

• https://nextjs.org/docs

• https://vitejs.dev/guide/

• https://vuejs.org/guide/

• https://vitest.dev/guide/

• https://parceljs.org/docs/

Thanks for the examples! What makes you think they're so good out of interest? The design? The content? The tone of voice? Etc.

[JS-GitRepo]

As someone relatively new to programming, I would LOVE if there were an implementation tutorial on using react-spring in react more holistically, rather than just completely isolated examples. Not necessarily a documentation issue for experienced devs, but for noobs like myself. Usually this is the space of youtube to cover, but I find tutorial content fairly sparse. Regardless, thank you greatly for your time and for a fantastic module!

[iamzapata]

These doc sites are good examples of good documentation:

• https://nextjs.org/docs
• https://vitejs.dev/guide/
• https://vuejs.org/guide/
• https://vitest.dev/guide/
• https://parceljs.org/docs/

Thanks for the examples! What makes you think they're so good out of interest? The design? The content? The tone of voice? Etc.

Things they have in common that I find that make the reading a better experience:

• font-size: larger
• line-height: larger
• content width: more narrow
• you know where you are within the documentation. Every content header has a section on the left, or on the right
• the content is easy to read / follow
• things are easy to find

divio documentation has a nice take and what documentation is and how to structure it.

[uguremirmustafa]

One thing that I find annoying is that popup on the right bottom of the page showing up on any page change. Please remove it 🙏

[AlulaLeak]

Please please please add a search bar. If not, atleast put everything on one page so we can use cmd+F. It's a fustrating guessing game to find anything. No disrespect, just my honest, fustrated opinion. Thanks.

[ChezFre]

Spring animations are like a holy grail for me. When I got my first iPhone I was mesmerised by being able to switch between screens with a fluid animation, or step-by-step by slowly sliding my finger across the screen. So when I first heard about react-spring I was obviously excited, but it's been a couple of years now and I still haven't grasped it.

The docs seem simple enough at first glance, a couple of hooks with fairly straightforward parameters. But then when you want to start implementing I still feel like I don't know where to start. What hook do I need for this specific animation, do I animate the parent with a useSpring or the children with a useSprings or useTrail.

The next logical step is to have a look at the examples, but these are often built on outdated versions of react-spring in combination with react-use-gesture that have incompatible APIs and seem to rely on a fair bit of abstract math to achieve the animations. What I'm missing there is a layer in between, something that starts with explaining the basics of the API and then some getting started guides with intermediate to advanced animations where the logic behind each step is explained. As it stands it goes from 1 to 100% with nothing in between. As is often the case with docs they probably make a lot of sense to the people that don't actually need them anymore.

I was looking at this Youtube video earlier which seems like a perfect candidate for react-spring, but starting from the docs it just becomes too abstract for me to even get started

As for how the documentation is organised it does not make a whole lot of sense to me to start with the common section. When I'm looking for documentation I'm most likely looking for the hooks and how to use them. Why would I want to read about interpolation before I have even seen how the library itself works? Interpolation is a more advanced step that I wouldn't expect to need in my first basic animation. Same goes for the configs, for a first animation the defaults should be solid enough that I don't need to know the config.

I also feel like the language is sometimes more obscure than it should be. For example, when talking about properties that can be passed in to react-spring hooks it is described as: All primitives inherit the following properties (though some of them may bring their own additionally):.

A final important one for me, documentation should have versions and remain available when new major versions are published as https://date-fns.org/ does it for example (although the version you're currently looking at could be a bit more apparent to the user as they have it tucked away in the corner).

I do want to end with saying that the library itself is amazing and that this and framer motion have the potential to become the baseline for animating on the web.

[Aniganesh]

I was trying to use the useTransition hook and what I found difficult was that there is no types for any of the params it takes.
The following are questions that I would like answers to on the API page:
What is the shape of the object it needs?
What do the properties in the object do?
Maybe these are already documented somewhere but I have no way of knowing about them.

What I would also appreciate is full code to the examples that are there on the API page.

[dominiczaq]

I had big trouble with understanding how can I pass styles from parent component useTransition to child component. Only thing I could find in existing documentation was this: https://react-spring.io/basics#finally-tie-the-animated-values-to-your-view. This wasn't very helpful because it didn't elaborate how to pass styles and how to type it.

The second thing was that I had trouble understanding why useTransition and passing styles down to child component resulted in a lot of rerenders. Documentation did not provide much help. Finally I've stumbled upon this beautiful answer on SO https://stackoverflow.com/a/69780522/2607169 and linked codesandbox https://codesandbox.io/s/react-spring-elaborate-example-mn5pu which dives deep into explaining why this happened and how to fix it.

[joshuaellis]

Just wanted to say thank you everyone who gave feedback!! I've tried to take as much of it into account as possible, however some of it is better angled out the type and quality of our documentation as opposed to the design.

I've drawn up some of the content items i'm trying to tackle here – https://github.com/pmndrs/react-spring/projects/3

Items might come & go. But i've done an MVP design implementation so when i've added the Overview and Getting Started drafts, i'll release a beta and start a new thread series in Discussions for feedback on the beta.docs.

I'll be locking this issue after the beta is released.

[chiester]

1. Add a "Getting Started" for a quick start on how to install and the most basic working example. Make this the first thing people see.

2. Read https://diataxis.fr/ and re-work your documentation according to the four types of documentation.

[joshuaellis]

1. Add a "Getting Started" for a quick start on how to install and the most basic working example. Make this the first thing people see.

2. Read https://diataxis.fr/ and re-work your documentation according to the four types of documentation.

Great link! I'm actually in the middle of reading Docs for Developers, which discusses very similar practices and then a little bit more! Worth the read if anyone is interested in technical writing.

[richardHaggioGwati]

Overall I like the documentation and the library as a whole, I will use it in my current and future projects.

• The star animation is incomplete

<polygon points={POINTS} />

Points is not defined.

[Heilemann]

Just another vote, again, for removing the giant header on the docs pages. It's quite frustrating.

[joshuaellis]

Just another vote, again, for removing the giant header on the docs pages. It's quite frustrating.

you can stop repeating yourself, it's quite frustrating 😄

[Heilemann]

you can stop repeating yourself, it's quite frustrating 😄

My apologies, didn't mean to frustrate with the feedback the site asks for every time I open it ¯_(ツ)_/¯ 😄

For what it's worth I wanted to put my money where my mouth is and submit a PR to fix it, but I ran into various NPM dependency issues and was unable to get it up and running. More than happy to help out. <3

[joshuaellis]

you can stop repeating yourself, it's quite frustrating 😄

My apologies, didn't mean to frustrate with the feedback the site asks for every time I open it ¯_(ツ)_/¯ 😄

For what it's worth I wanted to put my money where my mouth is and submit a PR to fix it, but I ran into various NPM dependency issues and was unable to get it up and running. More than happy to help out. <3

You're welcome to get squarespace to sponsor this project and I'd be able to spend more time building the new docs 😊

P.S. did you try yarn?

EDIT: Props to you! 🙇🏻‍♀️

[Heilemann]

Well I'm fairly far removed from engineering at Squarespace and am using this in a personal capacity, but I don't mind sponsoring it a bit myself actually. Probably not enough for anyone to quit their day job, but maybe enough to get a few cups of coffee for those late nights 😄

I did not try yarn, but I will now!

[joshuaellis]

Hi Everyone,

Thank you again to everyone who's given feedback. I'm very happy to share the initial beta of the new docs site – https://beta.react-spring.dev/

As you'll no doubtably see, it is a WIP & I will be adding more documentation over the coming weeks most likely focussing on our component APIs (useTransition, useChain etc.). I think for now until the documentation is complete examples might take a back seat as I want to figure out the best way to display them in the site with filtering so people can find what they want as well as find the time to make some more "common use case" examples e.g. an slide-in panel!

I'd love to get more feedback on the site particularly around any bugs you find or surrounding the content you're reading, since this issue is going to be locked, lets move it to it's own discussion thread – #1931

And if you really hate, don't tell me 😉