[ATO 1080] create product documentation for markers

[vcidst]

Proposed changes:

• Add product documentation for Realtime Markers as per ATO-1080

Status (please check what you already did):

• added some tests for the functionality
• updated the documentation
• updated the changelog (please check changelog for instructions)
• reformat files using black (please check Readme for instructions)

[rgstephens]

How do you stop forwarding real-time markers?

[vcidst]

I'm sorry I didn't understand your question. Did you mean to ask how does one stop uploading the marker-configurations to rasa-pro-services? The marker-configurations are only forwarded to rasa-pro-services (referred as Analytics Data Pipeline in the documentation) when this command is run.

[rgstephens]

I have the impression that this command starts "real time processing" of markers and that it kicks off real-time forwarding of markers to the analytics pipeline by Rasa.

I must be confused about what happens when you run this command.

Does the command do a one time upload of markers to the analytics and then exit? Does it run and forward markers until you manually stop the command?

[vcidst]

This command uploads the marker-configuration(aka patterns) files and then exits. Rasa Analytics stores these patterns in a database table called rasa_patterns. To remove any pattern, you can remove them from the YAML file and run rasa markers upload again.

Rasa Analytics will then process all events from Kafka and extract any markers that it founds in the stream of events. The markers are extracted based on the patterns in rasa_patterns table. Extracted markers are stored in rasa_markers table

[rgstephens]

Can you add an example query and graph for markers on the Example queries page?

[vcidst]

I can add an example query and graph to visualise num_preceeding_user_turns for a marker that tracks when user has completed the form. It'll visualise the number of turns users took to complete the form and can help give insight if the users are struggling to complete the form. Will something like that be helpful? It's only one of the many use cases of this feature

[rgstephens]

A form related example would be really good. When Alana and I recently wrote the blog post on this subject, we really needed a completion rate example. For a given form or story, how many people started the form and how many completed it successfully.

[vcidst]

For a given form or story, how many people started the form and how many completed it successfully.

I'll add this example to this documentation

[vcidst]

@rgstephens With a release schedule of next week, we're short on time to add this example at the moment but I've created a ticket at https://rasahq.atlassian.net/browse/ATO-1227 for this and we'll add this example in a micro release

[rgstephens]

What's a "marker definition"? Above, it says "This command uploads the marker configurations to the data pipeline." and here it's talking about the "marker definitions are uploaded"?

[vcidst]

I agree that's a bit confusing. Marker definition or marker configuration refers here to the YAML files that describe the marker in the following manner,

marker_cheer_up_success:
  description: "Sequence of intent and action that define the marker_cheer_up_success"
  seq:
    - intent: mood_unhappy
    - action: utter_cheer_up
    - action: utter_did_that_help
    - intent: affirm

This information is used to identify when these event sequences occur in the conversation. Or, when marker_cheer_up_success is extracted from a conversation. To differentiate these, I have referred the YAML files as "marker-configuration" and the markers found in the conversations as "extracted markers".

Do you have any suggestions for making this distinction more clear and simplified?

[andreaklmn]

I ended up making Markers lower case everywhere to be a bit more consistent

[vcidst]

Hey @rgstephens, I've addressed the sections you pointed out and expanded on them. Since today is the release day, I'll go ahead and merge this PR. However, I still appreciate your input, so if you have any further thoughts or suggestions, please let me know. I'll make sure to incorporate them into the documentation in a micro release. Thanks!

[github-actions]

🚀 A preview of the docs have been deployed at the following URL: https://12527--rasahq-docs-rasa-v2.netlify.app/docs/rasa

Feedback still appreciated and can be addressed in a micro. However, today is release day