Ux study feedback #16124

rakshith91 · 2021-01-13T00:27:08Z

Recreating @KieranBrantnerMagee's PR #15729 here

sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py

swathipil

let me know if any of the comments are unclear (or incorrect) :)

sdk/eventgrid/azure-eventgrid/README.md

swathipil · 2021-01-13T19:02:09Z

sdk/eventgrid/azure-eventgrid/README.md

    "metadataVersion":"1",
    "eventTime":"2020-08-07T02:28:23.867525Z",
-    "topic":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/topics/eventgridegsub"
+    "topic":"/subscriptions/fake-subscription-id/resourceGroups/fake-resource-group/providers/Microsoft.EventGrid/topics/eventgridegsub"


Is there a reason for changing subscription-id and resource-group to fake-subscription-id and fake-resource-group? Same thing in line 208.

it's more clear according to some users in the ux study

swathipil · 2021-01-13T19:08:39Z

sdk/eventgrid/azure-eventgrid/README.md

 ### Send an Event Grid Event

 This example publishes an Event Grid event.
+> **Note:** It is important to know if your topic supports Cloud or EventGrid events beforehand, otherwise send() will throw an exception.


Small, potential change, for clarity. Something like:

Suggested change

> **Note:** It is important to know if your topic supports Cloud or EventGrid events beforehand, otherwise send() will throw an exception.

> **Note:** It is important to know if your topic supports Cloud or EventGrid events before publishing. If you send to a topic that does not support the schema of the event you are sending, send() will throw an exception.

swathipil · 2021-01-13T19:08:52Z

sdk/eventgrid/azure-eventgrid/README.md

 ### Send a Cloud Event

 This example publishes a Cloud event.
+> **Note:** It is important to know if your topic supports Cloud or EventGrid events beforehand, otherwise send() will throw an exception.


swathipil · 2021-01-13T20:12:34Z

sdk/eventgrid/azure-eventgrid/README.md

+A channel within the EventGrid service to send events.  Must be of CloudEvent or EventGridEvent schema, (decided at creation time) and the corrosponding event type must be used.
+
+### Domain Topic
+A domain exists to rout arbitrary named topics within it.  Topics must not exist beforehand if using a domain, topic name can be provided at send time.  Simply provide the domain endpoint at client construction instead of topic endpoint.


A little unclear on what is meant by Topics must not exist beforehand if using a domain, topic name can be provided at send time.? I tried creating a domain and publishing to the domain endpoint with the topic name specified, but the topic did not exist beforehand. It was published and reached the endpoint, but the event was not delivered to that topic. I had to manually name and create the domain topic in the portal (or management plane sdk) under the domain, and published again before it was delivered there.

Might be worthwhile to make it more clear how a domain topic works in comparison to other topics + to include things from this doc (https://docs.microsoft.com/en-us/azure/event-grid/event-domains) including the following:

More info on what a domain is: "An event domain is a management tool for large numbers of Event Grid topics related to the same application. You can think of it as a meta-topic that can have thousands of individual topics." The way it's phrased now doesn't really show why domains are used, how the individual topics are related, etc.

Publishing to a domain: "When you create an event domain, you're given a publishing endpoint similar to if you had created a topic in Event Grid...
To publish events to any topic in an Event Domain, push the events to the domain's endpoint the same way you would for a custom topic. The only difference is that you must specify the topic you'd like the event to be delivered to."

Links + typo + something like this?

Suggested change

A domain exists to rout arbitrary named topics within it. Topics must not exist beforehand if using a domain, topic name can be provided at send time. Simply provide the domain endpoint at client construction instead of topic endpoint.

A domain is a management tool that exists to route events to individual domain topics within it which are related to the same application. Publishing to a domain topic is similar to publishing to a custom topic. There are two key differences:

1. At client construction, the domain endpoint must be provided instead of topic endpoint.

2. The individual domain topic name must be specified in the event at send time. To be delivered to the domain topic provided, the domain topic must already exist in the domain.

More information about Event Domains can be found [here](https://docs.microsoft.com/en-us/azure/event-grid/event-domains).

as @swathipil mentioned, echoing words from the service doc is good.

also I'm feeling that as it is the Key concepts section, Domain topic could just describe the service concepts and we leave the details of client constructor ("only domain endpoint at client construction for domain topic..." etc.) could be placed under the EventGridPublisherClient section.

swathipil · 2021-01-13T20:15:37Z

sdk/eventgrid/azure-eventgrid/README.md

+
+### Send to a Domain
+
+This example illustrates sending to a Domain, whereas the earlier samples sent to a Topic.


This may add a little more clarity?

Suggested change

This example illustrates sending to a Domain, whereas the earlier samples sent to a Topic.

This example illustrates sending to a Domain Topic, whereas the earlier samples sent to a custom Topic.

why custom?

I thought it would be more consistent with the way we name the samples. For example, here or here. It may also make more sense to rename these samples to ...events_to_topic instead of events_to_custom_topic?

Co-authored-by: swathipil <[email protected]>

yunhaoling · 2021-01-15T01:12:44Z

sdk/eventgrid/azure-eventgrid/README.md

 Information about the key concepts on Event Grid, see [Concepts in Azure Event Grid][publisher-service-doc]

+### Topic
+A channel within the EventGrid service to send events.  Must be of [CloudEvent](https://docs.microsoft.com/azure/event-grid/cloud-event-schema) or [EventGridEvent](https://docs.microsoft.com/azure/event-grid/event-schema) schema, (decided at creation time) and the corresponding event type must be used.


add a bit clarity on the second half, feel free to tweak my words.

Suggested change

A channel within the EventGrid service to send events. Must be of [CloudEvent](https://docs.microsoft.com/azure/event-grid/cloud-event-schema) or [EventGridEvent](https://docs.microsoft.com/azure/event-grid/event-schema) schema, (decided at creation time) and the corresponding event type must be used.

A channel within the EventGrid service to send events. Event must be of [CloudEvent](https://docs.microsoft.com/azure/event-grid/cloud-event-schema) or [EventGridEvent](https://docs.microsoft.com/azure/event-grid/event-schema) schema which is decided at creation time. In the case of wrong event type being used, errors will be raised.

yunhaoling · 2021-01-15T01:40:12Z

sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py

    All required parameters must be populated in order to send to Azure.

    :param topic: The resource path of the event source. If not provided, Event Grid will stamp onto the event.
+        Is required for Domain topics, and a domain topic may be specified which doesn't yet exist.


so if I send the event to a domain topic which doesn't exist yet, the EventGrid would create a new domain topic for me?

yunhaoling · 2021-01-15T01:41:47Z

sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py

    All required parameters must be populated in order to send to Azure.

    :param topic: The resource path of the event source. If not provided, Event Grid will stamp onto the event.
+        Is required for Domain topics, and a domain topic may be specified which doesn't yet exist.


also, it seems over indented, not sure it would cause rendering issue

Suggested change

Is required for Domain topics, and a domain topic may be specified which doesn't yet exist.

Is required for Domain topics, and a domain topic may be specified which doesn't yet exist.

yunhaoling · 2021-01-15T01:42:33Z

sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py

+        be unique for each distinct event, and otherwise can be any user-defined string.
+If publishing to a domain topic, source must be the domain name.


indentation

Suggested change

be unique for each distinct event, and otherwise can be any user-defined string.

If publishing to a domain topic, source must be the domain name.

be unique for each distinct event, and otherwise can be any user-defined string.

If publishing to a domain topic, source must be the domain name.

rakshith91 · 2021-03-01T03:09:29Z

closing in favor of #16986 - addressed the above comments there too

Ux study feedback

ffcd5d3

rakshith91 requested review from KieranBrantnerMagee and lmazuel as code owners January 13, 2021 00:27

ghost added the Event Grid label Jan 13, 2021

rakshith91 mentioned this pull request Jan 13, 2021

[EventGrid] Adjust README verbiage in preparation for UX pilot study with feedback #15729

Closed

rakshith91 requested a review from yunhaoling January 13, 2021 00:43

rakshith91 commented Jan 13, 2021

View reviewed changes

sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py Outdated Show resolved Hide resolved

Update sdk/eventgrid/azure-eventgrid/azure/eventgrid/_models.py

a04eebf

rakshith91 requested a review from swathipil January 13, 2021 17:23

swathipil reviewed Jan 13, 2021

View reviewed changes

Apply suggestions from code review

c01bdc6

Co-authored-by: swathipil <[email protected]>

yunhaoling reviewed Jan 15, 2021

View reviewed changes

rakshith91 closed this Mar 1, 2021

	> Note: It is important to know if your topic supports Cloud or EventGrid events beforehand, otherwise send() will throw an exception.
	> Note: It is important to know if your topic supports Cloud or EventGrid events before publishing. If you send to a topic that does not support the schema of the event you are sending, send() will throw an exception.

-A domain exists to rout arbitrary named topics within it.  Topics must not exist beforehand if using a domain, topic name can be provided at send time.  Simply provide the domain endpoint at client construction instead of topic endpoint.
+A domain is a management tool that exists to route events to individual domain topics within it which are related to the same application. Publishing to a domain topic is similar to publishing to a custom topic. There are two key differences:
+. At client construction, the domain endpoint must be provided instead of topic endpoint.
+. The individual domain topic name must be specified in the event at send time. To be delivered to the domain topic provided, the domain topic must already exist in the domain.
+More information about Event Domains can be found [here](https://docs.microsoft.com/en-us/azure/event-grid/event-domains).


		### Send to a Domain

		This example illustrates sending to a Domain, whereas the earlier samples sent to a Topic.

	A channel within the EventGrid service to send events. Must be of [CloudEvent](https://docs.microsoft.com/azure/event-grid/cloud-event-schema) or [EventGridEvent](https://docs.microsoft.com/azure/event-grid/event-schema) schema, (decided at creation time) and the corresponding event type must be used.
	A channel within the EventGrid service to send events. Event must be of [CloudEvent](https://docs.microsoft.com/azure/event-grid/cloud-event-schema) or [EventGridEvent](https://docs.microsoft.com/azure/event-grid/event-schema) schema which is decided at creation time. In the case of wrong event type being used, errors will be raised.

	Is required for Domain topics, and a domain topic may be specified which doesn't yet exist.
	Is required for Domain topics, and a domain topic may be specified which doesn't yet exist.

		be unique for each distinct event, and otherwise can be any user-defined string.
		If publishing to a domain topic, source must be the domain name.

Ux study feedback #16124

Ux study feedback #16124

Uh oh!

Conversation

rakshith91 commented Jan 13, 2021

Uh oh!

Uh oh!

swathipil left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yunhaoling Jan 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rakshith91 commented Mar 1, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yunhaoling Jan 15, 2021 •

edited

Loading