Updates the readme

[MarcSkovMadsen]

This is an attempt to

• sharpen the elevator pitch
• describe hvPlot as it is today
• Make the communication more engaging using examples and images
• Make it easy to find what you need via menus and links.
• Mention hvPlot as the entry point to the HoloViz ecosystem (See hvPlot as the universal entry point to HoloViz tools #533).

You can see the README rendered here.

Additional Context

Maybe the rest of the HoloViz ecosystem READMEs could need a similar update?

[maximlt]

That section seems redundant compared with the first table.

[MarcSkovMadsen]

Maybe.

• I'm not sure its clear to users that they can click the buttons on the first table. Its also a mix of icons that are only "kpis" and icons for navigation.
• A lot of users don't know what to go to github with and what to go to discourse with. This tables makes it clearer.
• And this makes it very clear what kinds of support to expect.

:-)

[MarcSkovMadsen]

And then I like the idea of having a link at the top of the document called Support.

What is in this "menu" should be the most expected things users are looking for.

[MarcSkovMadsen]

Its not that important. Should I remove it @maximlt ? If yes should we include the twitter link in the top table (I think so 😄 )?

[maximlt]

Yes please I'd appreciate if you could remove the Support and Feeback section, which I think doesn't bring much to the table as the support link is already in the first table, and hvPlot doesn't (yet) have its own tweeter account.

[MarcSkovMadsen]

I just added Gitter and a note about the HoloViz call as feedback from Sophia Yang.

[sophiamyang]

I like the support table. It's what users care about: where to get help. I think the support table is more valuable than the first table. Users don't care about test coverage, releases, and so on...

[sophiamyang]

Yes adding the Twitter link is a great idea!

[MarcSkovMadsen]

Now we have been exploring and discussing a bit. Could you update me on what I should do to resolve this one @maximlt ? Thanks.

[maximlt]

We're currently focusing on making the next bug fix release of hvPlot and this PR isn't going to be part of it, since as whenever it is merged it is going to make the README directly better :)

I still need to have a look at the recent changes you've made!

[maximlt]

Thanks @MarcSkovMadsen !

The only thing I'm not sure I'm comfortable with is having images pulled from domains we don't control (e.g. medium). I'll see if I can find a better solution.

[MarcSkovMadsen]

Thanks @MarcSkovMadsen !

The only thing I'm not sure I'm comfortable with is having images pulled from domains we don't control (e.g. medium). I'll see if I can find a better solution.

For sure they should be hosted somewhere. But I don't have access to such a place managed by HoloViz. Normally philipp uploads them to aws for Panel.

[sophiamyang]

Thanks @MarcSkovMadsen !
The only thing I'm not sure I'm comfortable with is having images pulled from domains we don't control (e.g. medium). I'll see if I can find a better solution.

For sure they should be hosted somewhere. But I don't have access to such a place managed by HoloViz. Normally philipp uploads them to aws for Panel.

The Medium images can be found in the blog post repo https://github.com/sophiamyang/hvplot_interactive or the KDD tutorial repo https://github.com/holoviz-community/HoloViz_KDD2022. We can get the gif there instead of Medium.

[maximlt]

@MarcSkovMadsen @sophiamyang I reply to both of you here not for this interesting discussion to get lost in a thread.

I like the support table. It's what users care about: where to get help. I think the support table is more valuable than the first table. Users don't care about test coverage, releases, and so on...

I'm afraid I have to disagree on this point. The README on the Github repo is not meant to be the main entry point to users. If they hear about hvplot, the first thing they'll do imo is Google it, not search on Github. And when I google hvPlot, the first link I get is hvplot.holoviz.org, not a link to Github. Actually, I'd guess that most hvPlot users don't even have a Github account and aren't comfortable looking at its code on Github, and even at opening issues.

So I think the README on Github, that is also by the way the content rendered on PyPi, is more intended to dev users, and these users are more interested in code coverage, python supported versions, etc. I'll list a few examples of libraries that do show that at the beginning of their README:

• https://github.com/tiangolo/fastapi
• https://github.com/pandas-dev/pandas
• https://github.com/psf/requests
• https://github.com/matplotlib/matplotlib

I've picked libraries that do show these labels, there are of course others that don't ;) Yet it shows that this is standard practice.

This table is also useful for the maintainers, I actually use it very often to reach to some of the links it has, e.g. the link to the dev site or to codecov.

Yet it doesn't mean things can't be improved, this table has grown into a pretty large table and I guess things could be better arranged (it doesn't feel like a high priority to my eyes though, compared to updating the website itself 🙃 but I'll take whatever improves the current state).

Maybe the rest of the HoloViz ecosystem READMEs could need a similar update?

That is actually a very important point! It would be awesome if all the main HoloViz packages could share the same README template and styling. This would make for a coherent experience for users, and would make the life of the maintainers easier. Indeed I've been slowly converting the repos to use the same table at the beginning of their README, it made my life a lot easier. What I would suggest @MarcSkovMadsen is that it would be great if you could open an issue on https://github.com/holoviz/holoviz to discuss about the READMEs template and styling (e.g. the smileys in a sentence can easily confuse people, and I don't know how well they play with accessibility).

Yes adding the Twitter link is a great idea!

Well then yes okay! Not now though, hvPlot doesn't have its own account and we're discussing about how best to handle that, between creating a new account, renaming HoloViews, having all the plotting libraries refer to HoloViz_org, etc. Any feedback on this is very welcome.

[MarcSkovMadsen]

I would argue the FastApi is much more in line with this change. The project status is minimal and the rest is just an elevator pitch and introduction to the project for users. Not developers. He keeps the badges at the top to a minimum.

Streamlit is the same. There is almost no developer info https://github.com/streamlit/streamlit

Dash is also for users. https://github.com/plotly/dash

I believe its important to add some communication channel. And for now the most relevant is HoloViz or Holoviews. We can always change it later.

I would argue its much more important to get it right for potential users. There will be some coming there to learn about the project, report issues, some to star the project, some to evaluate the quality of the project, some to figure out if it is a nice project to contribute to, etc.

A very technical README is not very welcoming to new users.

[MarcSkovMadsen]

https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/ mentions "badges" and "contributions" as "Additional". Not as some of the most important things.

Github states a README is for the users. How to treat the developers is not mentioned. https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes

[MarcSkovMadsen]

I would argue that the argument for having badges at the top of the project is because they look nice and others do it. But it should not take up a lot of space. Is should be more in line with. The developers would be able to quickly spot what they need and the users would be able to skip it quickly.

[MarcSkovMadsen]

Just to see the effect in practice I minified the badges and moved them to the top. Looks like

The only thing I would says is that there are too many badges in all kinds of colors. Its distracting for users. Compare this to FastApi which is praised at the best at writing docs

[MarcSkovMadsen]

I've moved the project status table back to the top. It looks ok to me.

[MarcSkovMadsen]

Hi @maximlt

I've fixed the failing tests. Let me know if there is more I should do. Thanks.

[philippjfr]

Personally I'm very happy to see this merged, it's a huge improvement over what we have now. As maintainer @maximlt can revert changes when he gets back but for now I'm in charge (😈) and will merge.

[maximlt]

Thanks for merging! It's indeed an improvement 👍

There are a few things to fix though, like that table that shows that there's no bug in hvPlot. I doubt we have 0 bug, unless you have found an army of volunteers to work on hvPlot over my holidays! :D

I would also like:

• all the READMEs to be consistent over the HoloViz projects.
• not having to link to images that are hosted on Medium or any resource we don't control
• make sure the README is easy to maintain over time