search

readthedocs / readthedocs.org

The source code that powers readthedocs.org
https://readthedocs.org/
MIT License
8.05k stars 3.59k forks source link

Improve onboarding of manual imported projects #11720

Open stsewd opened 2 weeks ago

stsewd commented 2 weeks ago

What's the problem this feature will solve?

When a project is manually imported, the user may be required to do some extra steps:

Describe the solution you'd like

We should guide the user to complete these steps.

Alternative solutions

Do nothing, we already mention that manual steps are required when doing a manual import. Maybe link to the actual steps in the message.

Screenshot 2024-10-29 at 11-21-53 Add project - Read the Docs

Additional context

https://github.com/readthedocs/readthedocs.org/pull/11573#discussion_r1821150343

humitos commented 2 weeks ago

Do nothing, we already mention that manual steps are required when doing a manual import. Maybe link to the actual steps in the message.

I think adding links in this message is a good first step. However, I don't think it's the solution, since it's pretty easy to miss those link. If the user didn't click on those links while importing it, then they will be lost.

I suppose we can detect if the project was imported manually, and in that case add a new notification explaining there are probably missing steps (the ones you mentioned in the PR description). At that point, they can decide whether to follow those steps or ignore it and close it.

@agjohnson what are your thoughts here?

agjohnson commented 2 weeks ago

I've been looking for a notification here. I think the webhook integration page and deploy key pages could have some nicer onboarding in addition, but with the notification pointing to these pages.

The text up front is a lot to read and users will likely skip it. The notification forces interaction where any text is optional. Also, the project is not created yet, so on top of distracting users with a side quest they're also not able to change anything yet.

This was where we might have wanted to use notifications originally, and have the notification monitor these conditionals -- whether a project has a webhook or deploy key set up, etc.