Featured links could provide more specific support for claims

[mwaskom]

First of all, this page looks fantastic. I'm really digging the embrace of viridis as a visual identity for matplotlib!

As mentioned on gitter, I have some feedback about the choice of targets for some of the featured links. (Apologies if this is obvious and you are just thinking of these as placeholders while you iterate on the design!)

Specifically I'm thinking about this section:

This is prime real estate and these links will get thousands of clicks a day, many from people who are totally new to the project and want to understand what it's about. I think the bullet points advertise the key selling points of matplotlib very well. But the links in those bullets take users to parts of the docs that don't support the claims in a particularly specific or useful manner.

Going through them:

"Create publication quality plots" leads to the main example gallery. Opinions differ about what "publication quality" means, but many of the plots you immediately see are very basic demos, lacking features that you'd need to have in a publication (e.g. axis labels), and none demonstrate the polish that matplotlib is able to give to figures with a little effort. I've published plenty of figures that are 100% end-to-end matplotlib and this is absolutely a selling point, but poorly demonstrated by this link imo.

(It's also a bit overwhelming: you're on this lovely landing page, and then the first link takes you to an inventory of examples without a whole lot of narrative / organizational structure.)

"Make interactive figures that can zoom, pan, update." Also a selling point! But linking to the event handling examples makes this maybe seem more complicated than it actually is. With a GUI backend your plots zoom, pan, and update for free — matplotlib also lets you define custom interactions, which is what these examples demonstrate.

"Customize visual style and layout." This links to the homepage for the tutorials. I suppose that's a pretty general claim and so the tutorials are as good a place to go as any, but it's not especially demonstrative and I wonder about whether you want a user getting lost in the capacious docs on before reading more than a couple of bullets of the homepage.

"Export to many file formats" and "Embed in JupyterLab and Graphical User Interfaces" both link to the backend API docs, which are relevant but not in a way that's helpful or illustrative to someone new to the project.

"Use domain-specific plots from third-party packages." Perfect. No notes :)

---

IMO I am not sure that you need or want links on these bullet points. A lot of users are going to click on them and find themselves in the main docs without the helpful signposting that's on the lower half of the page, and I think you want a new user to get a high-level summary of what matplotlib offers before diving in.

But if you feel strongly that these claims need justification / demonstration, it would probably be worth thinking about what the best specific page to link to for each of them is. (Perhaps the lack of a specific target for some of these links is also a signal about what could be added to the docs. For instance, do the docs have a nice self-contained tutorial on "making (polished) publication-quality figures"?)

---

But again: page looks great, and I think people will really benefit from the work y'all are putting into this.

[mwaskom]

PS I also noticed that "usage guide" (in the next row of links) goes here which seems like a nonsequitor.

[story645]

Do you think there are sections in the examples gallery or tutorials that would be better to link to?

Alternatively, should there be new docs/tutorials, something like?

• Out of the box interactivity - pan, brush, zoom (basically what is sharex, how to set the data cursor, what are the widgets - the most basic out of the box built into mpl/the toolbar stuff)
• Publication quality plots - though what exactly would go here (for example if the gallery could be curated via tags?)

[mwaskom]

I don't think I have a great sense these days of what tutorials the matplotlib docs offer, so I'm not sure I'd be the one to say. But I guess it depends on what you want the links in this section to achieve.

For example, I do think it would be useful if matplotlib had a specific tutorial walking through the process of turning a couple "exploratory" plots into a polished multi-panel figure. If that existed, you could link to it from the "make publication-quality plots" bullet. But does a user who is just learning about matplotlib need that level of detail, even if it's something that interests them?

I (personally) don't think it makes sense to think of the introductory bullets as a table of contents (e.g. "here's where users should go if they want a link to the best page on making publication-quality figures"). To the extent that you want an interested user to click on a link, I would think it's best to offer a self-contained example that quickly and accessibly demonstrates what you're talking about. For the "publication-quality" figures, the best demonstration would probably be to link to a list of papers that cite matplotlib (or a showcase of matplotlib-powered papers). But for some of the general / high level claims, it's hard to know what that would be exactly (especially since several of the claims about, e.g. interactivity / gui frameworks are hard to quickly demonstrate in the static docs).

So, given that a lot of effort is going into structuring the rest of the page to guide users towards the right place in the docs, maybe it's best to just not have links in the "high level description of what matplotlib is about" section?

But again this is just my personal reaction!

[mwaskom]

Thinking about this more, maybe the best way to use this section is as a showcase for outputs of matplotlib. So: matplotlib can make publication quality plots? Here are thousands of papers that cite it (or highlight some of the most impactful ones). Matplotlib figures can be highly customized? Look at this picture of a black hole. Matplotlib can be embedded in a GUI? Here are some scientists using it to monitor a robot helicopter on another planet. Matplotlib can be used in a jupyter notebook? Here are dozens of free tutorials using it to spread data science skills across the world.

matplotlib has been used for some really cool applications — embrace and highlight that!

On the question of “where should such links go?” I still think you want to keep people on this page. There’s currently a gray box that I imagine is a placeholder for a static logo? What if instead that got dynamically populated with a little case study for each bullet point as users moused over them?

Finally I realized I actually do have a note on the domain specific libraries bullet ;). This is currently addressed towards a user “you can use third party libraries” but maybe better to address towards a developer of such libraries? “Use matplotlib to build a domain specific library or application” etc etc

[timhoffm]

Finally I realized I actually do have a note on the domain specific libraries bullet ;). This is currently addressed towards a user “you can use third party libraries” but maybe better to address towards a developer of such libraries? “Use matplotlib to build a domain specific library or application” etc etc

That's certainly to be considered. However, I think the main goal is to make people aware that there are tailored solutions for specific categories of plots and they do not necessarily have to tailor their specific plots using core matplotlib.

[mwaskom]

However, I think the main goal is to make people aware that there are tailored solutions for specific categories of plots and they do not necessarily have to tailor their specific plots using core matplotlib.

Yeah I don't think it's a big problem one way or the other it just reads as slightly weird to me. Matplotlib doesn't make it possible for you use third party tools exactly ... it makes it possible for those tools to exist, and then you use them.

[story645]

However, I think the main goal is to make people aware that there are tailored solutions for specific categories of plots and they do not necessarily have to tailor their specific plots using core matplotlib.

I think since domain specific section at the bottom of the page kinda highlights the third party packages from a user point of view, makes sense for that link to highlight it from a devs point of view (& the optimal thing to link to would probably be a style guide on writing third party libraries, some of which is buried in I think the usage guide)

[timhoffm]

Since 99.999% of visitors will be users, not authors of 3rd party libraries, I believe this most prominently placed bullet list should address their interests and not confuse them by to explanations they do not need.

Maybe we can refine the wording.

Use domain-specific plots from third-party packages built on top of Matplotlib.

or

Use domain-specific plots from packages extending Matplotlib.

[jklymak]

(EDIT) "Matplotlib is the foundation for a rich ecosystem of visualization packages" ?

[story645]

Since 99.999% of visitors will be users, not authors of 3rd party libraries

I totally agree and also I think we want more folks to start thinking of mpl as also a base for building their own libraries. (Is what a lot of what my work is supposed to be aimed at & is what ROSES is supposed to be partially aimed at).

I think Jody's wording here is pretty good:

Matplotlib is the foundation for a rich ecosystem of visualization packages

Maybe break out into

Use domain specific plot from packages built on top of Matplotlib Build your own reusable domain specific libraries and applications

[mwaskom]

Since 99.999% of visitors will be users, not authors of 3rd party libraries, I believe this most prominently placed bullet list should address their interests and not confuse them by to explanations they do not need.

FWIW I think a user who sees a bullet advertising that matplotlib can be extended by domain specific interfaces, along with a showcase of libraries that do that, will probably get the right takeaway, even if the bullet is technically addressed to potential authors of those libraries.

[timhoffm]

Matplotlib is the foundation for a rich ecosystem of visualization packages

Is ok. I'm not over-excited because in contrast to the other bullet points it just states a fact and does not tell the user how the fact relates to him. But when including that we either are at @story645's suggestion

Use domain specific plot from packages built on top of Matplotlib Build your own reusable domain specific libraries and applications

which I find a bit long (and reiterating from above, when setting priorities, advertising to everybody to actively build libraries on top of Matplotlib is not a title-page goal to me). N.b. I support the idea that people should write custom plot functions for their needs, but that's a different level of "build on top of Matplotlib" than a public plotting package; and user plot functions are more a usage detail than a top-level feature. So I still would not mention that here. That's something for the tutorial.

FWIW I think a user who sees a bullet advertising that matplotlib can be extended by domain specific interfaces, along with a showcase of libraries that do that, will probably get the right takeaway, even if the bullet is technically addressed to potential authors of those libraries.

I'd like to invert the statement: The few new (potential) library authors are reasonably experienced developers. They will realize that they can write a library on top of Matplotlib if they see that there are a number of those already.

In summary:

I'd be happy with either

Matplotlib is the foundation for a rich ecosystem of visualization packages

or

Use domain specific plots from packages built on top of Matplotlib

[story645]

Matplotlib is the foundation for a rich ecosystem of visualization packages

can probably be worked into the top line copy:

Matplotlib is a comprehensive library for creating static, animated, and interactive visualizations in Python. It is the foundation for a rich ecosystem of visualization packages by making easy things easy and hard things possible.

The few new (potential) library authors are reasonably experienced developers. They will realize that they can write a library on top of Matplotlib if they see that there are a number of those already.

I think the "you can build on top of us" is aimed at funders, managers, program managers- basically folks who developers may have to convince that mpl is a useful tool.

[tacaswell]

I think this was closed by #21