[docs] Update readme files (draft!)

[stichbury]

From what I can tell, there are two, almost identical README files:

• in the root of the repo
• in the vizro-core folder

Then there's a separate README in vizro-ai

This is the edit for the first pair, and I've made changes just in the vizro-core file for now. SEE IT HERE!

At the top, I've made a few suggestions to modify the tag line from "Vizro is a toolkit for creating modular data visualization applications" and I've also made a pair of suggestions to replace the "Rapidly self-serve..." sentence with one version from me and one from @antonymilne that are a bit more "analytical" in breaking down the messaging.

The originals are left in place, but with a strikethrough, so it's easy to see and compare.

From line 98 in the new version I've just edited in place, and these are light changes to wording and capitalisation.

I've not yet added the section about plugins as I'm not sure what is needed here.

TL;DR Some suggested edits in draft, for obvious reasons, for discussion. Should be sufficient to seed a discussion with @antonymilne @Joseph-Perkins and anyone else interested at this point.

• [ ] I acknowledge and agree that, by checking this box and clicking "Submit Pull Request":

  • I submit this contribution under the Apache 2.0 license and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
  • I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
  • I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
  • I have not referenced individuals, products or companies in any commits, directly or indirectly.
  • I have not added data or restricted code in any commits, directly or indirectly.

[antonymilne]

I could talk about this all day, and I think it's a very important topic so probably should do so at some point... but for now let me just leave a few thoughts 😀

For context, when we started the repo we only had one package, vizro. When we released vizro-ai, the repo became a monorepo, hence the folders vizro-core and vizro-ai. The README.md inside vizro-core is therefore (close to) the "original", and the one at the repo root was spawned off that when we moved to monorepo. I don't think much thought has been put into how to coordinate between these different READMEs, but it's worth bearing in mind that (IMO anyway) vizro is the primary resident of our repo rather than vizro-core and vizro-ai being equal siblings. So in that sense it's correct that the README in the repo root is dominated by vizro-core stuff.

Generally I'm very much in favour of these changes to our README, landing page on RTD, explanation/"Why Vizro" page, etc. I'm happy to be much more drastic about it, so as far as I'm concerned none of the content that we currently have is set in stone. In fact I think it's right to actively think about changing it because it's clearer to us what our value proposition is now compared to when we released.

I think what would help here is if we think about who this README is designed for. Very broadly, we have two groups of users:

• open source
• internal

At the moment I think much of our content is more suitable for consumption by internal rather than OS users. My personal preference would be to do this the opposite way round: tailor our public content to OS users and then maintain separate collateral for internal users. McK-esque phrases like "rapidly self-serve..." I think are actually very relevant and valuable for internal users but not OS users. So I'd be happy to remove it from the repo but think we should have this sort of content elsewhere. No doubt this situation is very similar to kedro, so curious what you think possible solutions are here. Because we don't want to have to duplicate everything into McKinseyish for internal users.

Now, onto the content itself... Definitely I think we need some catchy one line summary of what we do. At the moment there's kind of three of these on the page:

• "Visual Intelligence. Beautifully engineered"
• "Vizro is a toolkit for creating modular data visualization applications." or one of its suggested replacements
• "Rapidly self-serve the assembly of customized dashboards in minutes - without the need for advanced coding or design experience - to create flexible and scalable, Python enabled data visualization applications" or one of its suggested replacements

This feels like too many different catchphrases. "Visual Intelligence. Beautifully engineered" is kind of nice and plays into the QB brand but we don't use it anywhere else I think , and it doesn't really explain what we do, so not sure what its value is? Or if we like it a lot then we need something else as well that explains what we do.

Now, what should an explanatory (or the only) catchphrase be? "Vizro is a high-level framework built on top of Dash for quick and easy creation of beautiful multi-page dashboards" is what I used on the Dash forum. It's not miles off the mark but definitely tailored to Dash users, so I don't think exactly that is suitable for use here because it's a broader audience.

I'd suggest something like:

Vizro is a high-level framework for quick and easy creation of beautiful dashboards

Somewhere prominently we should explain that we're built on top of Dash and Pydantic, but that doesn't need to be part of the tagline, and it's already conveyed at a glance pretty well by the picture I think.

[stichbury]

Thanks @antonymilne I think we are broadly aligned. I've chatted with @Joseph-Perkins and I'm going to set up a session for us to discuss (so you get the chance to talk all day!) in the coming week or so.

[stichbury]

Closing this for now -- I'll create a new PR from the branch when it's ready.