Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Revamp the notifications #19615

Merged
merged 9 commits into from
Feb 11, 2020

Conversation

mbrookes
Copy link
Member

@mbrookes mbrookes commented Feb 9, 2020

image

image

@mui-pr-bot
Copy link

mui-pr-bot commented Feb 9, 2020

Details of bundle changes.

Comparing: e534b94...9f7287e

bundle Size Change Size Gzip Change Gzip
docs.main ▲ +6.63 kB (+1.11% ) 603 kB ▲ +1.68 kB (+0.86% ) 196 kB
@material-ui/core -- 362 kB -- 98.9 kB
@material-ui/core[umd] -- 318 kB -- 92 kB
@material-ui/lab -- 194 kB -- 57.3 kB
@material-ui/styles -- 51.4 kB -- 15.4 kB
@material-ui/system -- 16.4 kB -- 4.3 kB
Alert -- 83.6 kB -- 26.3 kB
AlertTitle -- 64.4 kB -- 20.3 kB
AppBar -- 64.2 kB -- 20.1 kB
Autocomplete -- 132 kB -- 41.4 kB
Avatar -- 65.4 kB -- 20.6 kB
AvatarGroup -- 62.4 kB -- 19.6 kB
Backdrop -- 68 kB -- 21 kB
Badge -- 65.5 kB -- 20.4 kB
BottomNavigation -- 62.6 kB -- 19.6 kB
BottomNavigationAction -- 75.7 kB -- 23.9 kB
Box -- 72 kB -- 21.8 kB
Breadcrumbs -- 67.9 kB -- 21.3 kB
Button -- 79.9 kB -- 24.5 kB
ButtonBase -- 74.2 kB -- 23.3 kB
ButtonGroup -- 83.4 kB -- 25.5 kB
Card -- 63 kB -- 19.7 kB
CardActionArea -- 75.3 kB -- 23.7 kB
CardActions -- 62.2 kB -- 19.5 kB
CardContent -- 62.1 kB -- 19.5 kB
CardHeader -- 65.2 kB -- 20.5 kB
CardMedia -- 62.5 kB -- 19.7 kB
Checkbox -- 83.2 kB -- 26.3 kB
Chip -- 82.8 kB -- 25.4 kB
CircularProgress -- 64.3 kB -- 20.3 kB
ClickAwayListener -- 3.91 kB -- 1.55 kB
Collapse -- 68.2 kB -- 21.1 kB
colorManipulator -- 3.88 kB -- 1.52 kB
Container -- 63.3 kB -- 19.8 kB
CssBaseline -- 57.7 kB -- 18.1 kB
Dialog -- 83.2 kB -- 25.9 kB
DialogActions -- 62.3 kB -- 19.5 kB
DialogContent -- 62.4 kB -- 19.6 kB
DialogContentText -- 64.2 kB -- 20.2 kB
DialogTitle -- 64.4 kB -- 20.2 kB
Divider -- 62.9 kB -- 19.8 kB
docs.landing -- 56.4 kB -- 14.5 kB
Drawer -- 85 kB -- 25.8 kB
ExpansionPanel -- 72.5 kB -- 22.7 kB
ExpansionPanelActions -- 62.2 kB -- 19.5 kB
ExpansionPanelDetails -- 62.1 kB -- 19.5 kB
ExpansionPanelSummary -- 78.3 kB -- 24.8 kB
Fab -- 77 kB -- 24 kB
Fade -- 23.4 kB -- 7.98 kB
FilledInput -- 73.7 kB -- 22.9 kB
FormControl -- 64.6 kB -- 20.2 kB
FormControlLabel -- 65.7 kB -- 20.6 kB
FormGroup -- 62.2 kB -- 19.5 kB
FormHelperText -- 63.5 kB -- 20 kB
FormLabel -- 63.6 kB -- 19.8 kB
Grid -- 65.3 kB -- 20.5 kB
GridList -- 62.6 kB -- 19.7 kB
GridListTile -- 63.9 kB -- 20 kB
GridListTileBar -- 63.4 kB -- 19.9 kB
Grow -- 24 kB -- 8.19 kB
Hidden -- 66.1 kB -- 20.8 kB
Icon -- 63 kB -- 19.7 kB
IconButton -- 76.3 kB -- 23.8 kB
Input -- 72.7 kB -- 22.7 kB
InputAdornment -- 65.3 kB -- 20.5 kB
InputBase -- 70.8 kB -- 22.2 kB
InputLabel -- 65.5 kB -- 20.5 kB
LinearProgress -- 65.5 kB -- 20.5 kB
Link -- 66.8 kB -- 21.1 kB
List -- 62.5 kB -- 19.5 kB
ListItem -- 77.3 kB -- 24.2 kB
ListItemAvatar -- 62.3 kB -- 19.5 kB
ListItemIcon -- 62.3 kB -- 19.5 kB
ListItemSecondaryAction -- 62.2 kB -- 19.5 kB
ListItemText -- 65.1 kB -- 20.5 kB
ListSubheader -- 62.9 kB -- 19.8 kB
Menu -- 89 kB -- 27.4 kB
MenuItem -- 78.4 kB -- 24.5 kB
MenuList -- 66.2 kB -- 20.7 kB
MobileStepper -- 68 kB -- 21.4 kB
Modal -- 14.5 kB -- 5.04 kB
NativeSelect -- 77 kB -- 24.3 kB
NoSsr -- 2.19 kB -- 1.04 kB
OutlinedInput -- 74.7 kB -- 23.3 kB
Pagination -- 86.2 kB -- 26.3 kB
PaginationItem -- 82.4 kB -- 25.5 kB
Paper -- 62.5 kB -- 19.5 kB
Popover -- 83.3 kB -- 25.8 kB
Popper -- 28.8 kB -- 10.3 kB
Portal -- 2.92 kB -- 1.3 kB
Radio -- 84.2 kB -- 26.5 kB
RadioGroup -- 64.6 kB -- 20.1 kB
Rating -- 70.7 kB -- 22.7 kB
RootRef -- 4.24 kB -- 1.64 kB
Select -- 117 kB -- 34.6 kB
Skeleton -- 63.1 kB -- 20 kB
Slide -- 25.5 kB -- 8.71 kB
Slider -- 76.8 kB -- 24.2 kB
Snackbar -- 75.6 kB -- 23.7 kB
SnackbarContent -- 63.7 kB -- 20.1 kB
SpeedDial -- 86.4 kB -- 27.2 kB
SpeedDialAction -- 119 kB -- 37.5 kB
SpeedDialIcon -- 64.7 kB -- 20.4 kB
Step -- 62.8 kB -- 19.7 kB
StepButton -- 82.6 kB -- 26.1 kB
StepConnector -- 62.9 kB -- 19.8 kB
StepContent -- 69.3 kB -- 21.7 kB
StepIcon -- 64.8 kB -- 20.2 kB
StepLabel -- 68.8 kB -- 21.7 kB
Stepper -- 65.1 kB -- 20.6 kB
styles/createMuiTheme -- 16.5 kB -- 5.81 kB
SvgIcon -- 63.2 kB -- 19.8 kB
SwipeableDrawer -- 92.4 kB -- 28.8 kB
Switch -- 82.3 kB -- 26 kB
Tab -- 76.5 kB -- 24.2 kB
Table -- 62.7 kB -- 19.7 kB
TableBody -- 62.3 kB -- 19.5 kB
TableCell -- 64.2 kB -- 20.2 kB
TableContainer -- 62.1 kB -- 19.5 kB
TableFooter -- 62.3 kB -- 19.5 kB
TableHead -- 62.3 kB -- 19.5 kB
TablePagination -- 144 kB -- 41.9 kB
TableRow -- 62.7 kB -- 19.7 kB
TableSortLabel -- 77.6 kB -- 24.4 kB
Tabs -- 85.8 kB -- 27.2 kB
TextareaAutosize -- 5.12 kB -- 2.14 kB
TextField -- 125 kB -- 36.6 kB
ToggleButton -- 76.3 kB -- 24.2 kB
ToggleButtonGroup -- 63.4 kB -- 20 kB
Toolbar -- 62.5 kB -- 19.6 kB
Tooltip -- 102 kB -- 32.4 kB
TreeItem -- 74.2 kB -- 23.5 kB
TreeView -- 66.8 kB -- 21.1 kB
Typography -- 63.8 kB -- 20 kB
useAutocomplete -- 14.7 kB -- 5.31 kB
useMediaQuery -- 2.58 kB -- 1.07 kB
Zoom -- 23.5 kB -- 8.09 kB

Generated by 🚫 dangerJS against 9f7287e

@oliviertassinari
Copy link
Member

Interesting! I was recently thinking of something related to it. What if we could easily display a full-width banner like we were doing for v3 https://v3.material-ui.com/ and like https://www.gatsbyjs.org/ has?

@mbrookes
Copy link
Member Author

mbrookes commented Feb 9, 2020

It isn't quite as intrusive as Snackbar based notifications, but I think it should still be reserved for important announcements such the the v4 one.

Not liking the Gatsby ads banner much.

@mbrookes mbrookes added the docs Improvements or additions to the documentation label Feb 9, 2020
@oliviertassinari
Copy link
Member

oliviertassinari commented Feb 9, 2020

Does taking the time to communicate about non-important messages on the documentation worth it? Could Twitter, only, be used for it? I think that we could have 3 categories of communication:

  1. Top header, for really important messages, like the release of a new major version, a new product class offering, etc. We can only display one message and change it at a low frequency.
  2. The Snackbar for important messages the developers can benefit from, like new minor releases, new blog posts, hiring, etc.
  3. Twitter for anything that is informative.

I think that we should be cautious that if it significantly reduce the reach, there is a chance we will no longer take the time to leverage this communication channel. Will it reduce the reach? I have no idea :)

@eps1lon
Copy link
Member

eps1lon commented Feb 9, 2020

I generally would not want any notifications there. If people want to subscribe to changes, news, updates etc then there are plenty of opt-in features (twitter, github, do we have a rss feed for the blog?).

These popups are just bad. They are driven by engagements which is usually used as a target not a metric.

I really like the single-popup approach as a compromise. Do we limit it to the last 2 announcements? Or only criticals (breaking changes, security fix) and last x updates?

@mbrookes
Copy link
Member Author

mbrookes commented Feb 9, 2020

if it significantly reduce the reach, there is a chance we will no longer take the time to leverage this communication channel

If anything, it could have the potential to increase engagement. The Snackbar is easy to dismiss (and likely to be if the developer came to the docs for a specific purpose, and the Snackbar is getting in the way of achieving their goal), and once gone, are never seen again. With the Notification icon, visitors to the site have the option to check the notifications in their own time, and to revisit them later if desired.

Anecdotally (sample size of 1), For Crowdin and YouTube that have similar notification systems, I always check them when there's an update.

@mbrookes
Copy link
Member Author

mbrookes commented Feb 9, 2020

Do we limit it to the last 2 announcements?

I don't recall there ever being more than 3 at one time, which for the Snackbar is almost too many for a first time visitor to be bombarded with, but 3 - 4 should be fine for a single user-initiated pop-up. For regular visitors there will never be more than one new announcement, and fairly infrequently at that.

I did wonder about the option to permanently dismiss a notification (if I follow on Twitter, I don't need to be constantly reminded every time I look at the notifications), but opted for the simpler approach initially.

Or only criticals

I don't think significant release or feature announcements (for example a new component) would be unreasonable to have a notification for when it's something that a developer who lives in the docs and not on the GitHub repo would benefit from learning about.

@oliviertassinari
Copy link
Member

oliviertassinari commented Feb 9, 2020

I really like the single-popup approach as a compromise.

@eps1lon How do you see this tradeoff being implemented?

It could have the potential to increase engagement.

@mbrookes Fair, it could have the reverse impact! Maybe we should track it (GA)?

@oliviertassinari
Copy link
Member

oliviertassinari commented Feb 9, 2020

for example a new component

I was wondering about using a standalone badge (BTW, something we could support!):

Capture d’écran 2020-02-09 à 13 42 45
https://orbit.kiwi/components/tilegroup/

Capture d’écran 2020-02-09 à 13 45 13
https://blueprintjs.com/docs/#core

Capture d’écran 2020-02-09 à 13 46 01
https://vuetifyjs.com/en/getting-started/quick-start

Copy link
Member

@oliviertassinari oliviertassinari left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the UI/UX of the popup, what do you think of:

  • Using a theme.palette.text.primary instead of the secondary color.
  • Display the popup below the icon (so we can see it)
  • I doubt we should have a modal like behavior (Popover). Would the usage of the Popper be more appropriate?

@mbrookes
Copy link
Member Author

mbrookes commented Feb 9, 2020

Do we limit it to the last 2 announcements?

Both Crowdin and Youtube make this a scrolling list with past notifications overflowing. In the case of Crowdin, which is closest to our use-case, they show two notifications before you need to scroll.

@@ -1,15 +1,18 @@
[
{
"id": 27,
"text": "You can <a style=\"color: inherit;\" target=\"_blank\" rel=\"noopener\" href=\"https://twitter.com/MaterialUI\">follow us on Twitter</a> to receive exclusive tips and updates about Material-UI and the React ecosystem."
Copy link
Member

@oliviertassinari oliviertassinari Feb 10, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe (looking for stats to support it, hold on) this message has been driving most of our new followers on Twitter. Should we keep it?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • The message was introduced In October 2018: eaa0052
  • We went from an average of 70 new followers/month to 300 since then.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We went from an average of 70 new followers/month to 300 since then.

What did we get from the twitter followers? More poll participation, comments, issue participation in linked issues?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The pros I can think of Twitter followers:

  • Reach our users even when they are not directly using the product (polls, discussions)
  • Reach the React community at large, when our users' retweet

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we keep it?

My logic for removing it was that it isn't news or an announcement, and we already have the twitter followers button (and footer link) on the home page. A better use might be, for example, to announce Twitter polls here, and in the poll tweet put "Follow @MaterialUI for the final results of this poll".

Copy link
Member

@oliviertassinari oliviertassinari Feb 10, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would be careful with the operational cost of using multiple channels for the same use case, but for important news, like the survey, it would definitely be interesting. Removing this message could be a way to measure the impact.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, let's try it and see. If Twitter follower growth tanks, we'll have to reevaluate what the best method to promote the twitter account is.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The pros I can think of Twitter followers:

Sure but this is just a hypothesis. Did the participation in polls increase?

What do we get in retweets? Did you see download/funding increase?

As far as I can tell we're not monetizing the twitter account, right? It's only a promotional channel so we should see the effects on that in download/funding numbers.

@oliviertassinari
Copy link
Member

oliviertassinari commented Feb 10, 2020

Very interesting!

  1. The appearance transition wasn't working because the ClickAwayListener was preventing the props to spread on the underlying element.
    Capture d’écran 2020-02-10 à 16 28 41
    I wonder if we shouldn't apply the same tradeoff than with the Tooltip: <Tooltip foo="bar"><div /></Tooltip> You will find foo="bar" applied on the div.
  2. The use of the disablePortal prop was required because of [ClickAwayListener] Handle portaled element #18586.

We might have two opportunities to improve the DX :).

@mbrookes
Copy link
Member Author

Thanks. Shame on me for not checking the console! 😊

@oliviertassinari oliviertassinari merged commit dbc1aee into mui:master Feb 11, 2020
@mbrookes mbrookes deleted the docs-revamp-notifications branch February 11, 2020 21:27
@mbrookes
Copy link
Member Author

This is one I can't wait to see go live! The Snackbar based notification has bugged me for ever – and I implemented it. 😆

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Improvements or additions to the documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants