Please announce and document major changes when they are made live!

tl;dr: I would really appreciate a workflow change to write documentation updates before release and notifications immediately after.

A new way to handle the data source recently went through a major change in several components like Select, Listbox and Segmented Control. It significantly changes how you set the data source and how you read the values.

I think it is a very good change. But I had to figure it out myself, and I still don't know if I have discovered all the differences and their repercussions and new best practices and such. No announcement was made or updated documents made available. A change like this should maybe come with a Blog post that brings us fully onboard with the new way of doing things.

For minor changes like adding a single property or a new style color option, no broadcast announcement need be made, but the docs should still reflect the change right away.

For major changes like this recent one, more effort needs to be made to tell developers what they are and how to use them.

I check the What's new on Retool every week, but that has not been updated on the regular lately and the changes may have happened days earlier.

Maybe we need a What's New section on the forum that is updated every time a change is pushed out. Then we could Watch that section to get immediate updates of changes in our email.

5 Likes

Hi @bradlymathews! Thank you for the thoughtful post. I'm sorry for the frustration this caused.

The docs for the new option list editor are up now (link). We'll also have an in-app link in the next day or so. We absolutely should have included this before we started rolling out.

The changelog has indeed been delayed, but weekly updates will return tomorrow. This will include retroactive posts for the previous 2 weeks. Also, we're going to move to including new features the week that they start rolling out instead of waiting until the final week.

For big changes in between changelog updates, we've been including in-app callouts to introduce the change (see screenshot). Granted, this one should have included a link to the docs to be of use. That will be updated tomorrow as well.

Last but not least, if you have any thoughts on the update itself, please let us know! Your feedback is always super valuable.

Cheers,
Garrett

3 Likes