Shareable Viz documentation

[stephkaiser]

Description

This ticket is created for the first version of shareable Viz documentation. Context - We want to test the full user journey of shareable viz and need the docs for a part of it.

Related to - #1116

Checklist

• Include labels so that we can categorise your feature request

[amandakys]

just leaving a note for docs updates after the testing sessions:

• I expect that internally we might get some questions about how to control permissions. It might be worth highlighting that this is controlled by AWS and where to find relevant docs
• It might also be useful to reiterate that you shouldn't commit your credentials.
• I also think we should align on terminology, hosted, deployed, vs shareable URLs. My view is that shareable URL is a bit of a tautology, it doesn't actually mean anything, since a URL is by default shareable. The feature is better described as Hosted Viz or Deployed Viz.
• Also since we only support AWS (for now) a better title for the docs might be "Deploy Kedro Viz on AWS" or something similar

[tynandebold]

Nice, thanks for that, Amanda. I just pushed a change to my docs PR based off of some of your feedback. Let me know what you think.

A couple other thoughts:

since a URL is by default shareable

I don't think this is true, or maybe it depends on how we define shareable. To me, http://localhost:4141/ is a URL that isn't shareable in that the content is highly likely to be inconsistent depending on who opens it. I do think we should converge on a term for this though, because "shareable URLs" is a little odd.

Some very quick market research yields that the term deploy and its derivations is one often used (e.g. Netlify, Vercel). Another is publish (e.g. GitHub).

I've changed the title of our docs page to this: Deploy a Kedro-Viz project

To the point about only offered on AWS, I think we can be explicit with the subheaders and leave the top-level title as is.

cc @stichbury

[stichbury]

I'm slightly concerned about "deploy" as that implies (to me, a naive reader) that it's about the process of putting a pipeline etc on the cloud, and if I'm a user and I want to "just share my Viz to my stakeholder so they can play with it" that's probably not what I'm going to search for or look at.

Can I just check too -- we aren't deploying the whole Kedro project and code to S3 are we? Just the facility to spin up a Viz and explore it? So I think i'd be cautious about "deploy" without qualification. I do totally agree we need to align terminology though.

Let me propose a few tweaks to try to capture this...

[stichbury]

OK, there's some new copy in kedro-org/kedro#3079

[rashidakanchwala]

just saw @amandakys comment ... and yeah I was thinking the same -- if "Shareable Viz" should be called "Hosted Kedro-Viz".
On the docs, it's now referred to as "Kedro-Viz sharing". To me, when I read "Kedro-Viz sharing", the idea of hosting doesn't immediately come to mind.
However, the term "Hosted Kedro-Viz" clearly conveys that I can share the visualization given that it is hosted somewhere.

What do you all think? @tynandebold @stichbury @stephkaiser @amandakys

[stichbury]

I think the only problem I have with "Hosted Kedro-Viz" is not so much with the "hosted" part but the "Kedro-Viz" part 😆

The reason being, and this is really pedantic, is that Kedro-Viz is our product and what is being hosted is a visualisation of someone else's project. It's really splitting hairs!

I've kind of reflected that thinking in the latest version in the PR. If you want to edit further to modify the "share" to "host" wherever you think it works, I am happy as long as you are all in consensus. I'll leave it with you, because I don't have strong opinions either way on that...but I would prefer to avoid "deployed".

[astrojuanlu]

FWIW, +1 for "publish", +0 for "deploy". I think they're basically synonyms for this use case (and @tynandebold showed above that both are used), and picking "publish" for this helps us keep "deploy" for "deploying Kedro projects", which implies more complexity. My 2 cents

[tynandebold]

Thanks, everyone. I think Publish works well. I'll reflect where it's needed, and also in the UI, e.g.:

[tynandebold]

https://kedro--3079.org.readthedocs.build/en/3079/visualisation/share_kedro_viz.html

[stichbury]

This is great, thanks @tynandebold

The only thing I now have an issue with, sorry, is the title "Publish and share Kedro-Viz".

Partly because of the unfortunate way that capitalisation works out. Which isn't that big a deal.

But also, I'm not sure, isn't Kedro-Viz our product, so what the user is sharing is a project visualisation, or maybe at best, a project Kedro-Viz.

So would "Publish and share a project's Kedro-Viz" ? be better? Or "Publish and share your project's visualisation" or something combining both?

If you are happy to use "Kedro-Viz" to refer to what the user is sharing, I guess I'm OK with it, but it does seem like we are conflating our product/package with the user's project and that could cause some confusion ??

[stichbury]

PS: This is why it takes so long to publish books. The title takes at least 3 months negotiation 😆

[rashidakanchwala]

Publish and share your Kedro-viz visualisation or Publish and share your Kedro-viz flowchart ??

[tynandebold]

Thanks, both. I think we're starting to split hairs a bit here though. To me, "Publish and share Kedro-Viz" isn't confusing or conflating.

To try and remove myself, I've asked @stephkaiser to temperature check this in her two user interviews she's conducting today, so let's see what she comes back with!

[amandakys]

Just piling on 😆 I think Publish and Share is a bit overkill - they largely mean the same thing? In our user interviews, some also likened the concept to exporting, like export to local, export to cloud.

If we want to be specific about not sharing the whole 'product of Kedro Viz' perhaps something like 'Share your Kedro Viz
instance' to emphasis that you're sharing your local version?

[stephkaiser]

hey team, thanks for the suggestions above its been very helpful! Let me share my thoughts below

@stichbury i understand your point that users are actually sharing their projects visualisation rather than the Kedro-Viz product however, i feel those two are quite synonymous. Users are essentially sharing their versions of kedro-viz which is a visualisation of their pipelines. Let me know what you think here - it would be nice to keep the title as short as possible too, "Publish and share a project's Kedro-Viz" feels too wordy for me?

My suggestion would be to keep it simple with "Share Kedro-Viz" and if users need more information they can easily access the docs within the shareable Viz feature as well to read more - in fact they will need to read the docs first before they can use the feature anyways as there are pre-requisites for the feature to function. Also, we are getting strong indications that users prefer/want a platform-agnostic way of sharing kedro-viz so we might not necessarily be "publishing" anything for users if you get what I mean. However this is definitely not in the first version of shareable-viz and we still need to evaluate technical feasibility for this.

Another note - in our usability tests i've been describing the feature as "sharing kedro-viz" and so far users understand what this means. If we notice any confusion in the future, we could tweak/improve the language again too.

[tynandebold]

Based on all this input, I don't think I'm going to make any changes from what we have now. It seems sufficient, general purpose, and understandable.

If anyone wants to have a last look, here's the preview URL for the docs, which also shows a GIF showing the UI with the same language: https://kedro--3079.org.readthedocs.build/en/3079/visualisation/share_kedro_viz.html

I'll merge tonight unless anyone has strong objections.

[stichbury]

No strong objections. Your original title is fine and I like Steph's point that we can "read the room" and tweak if needed.