Make it easier to understand what a feed is

andreasnauerz commented 8 years ago

Based on the latest labs/user studies we ran, it seems that people still have a lot of trouble with understanding what a feed is (cp. the feedback I have shared via mail already).

Quote: "I do not really get what a feed is; all other concepts are easy to understand, but this feed thing puzzles me even though I saw it several times"

Since I got similar feedback several times now, the question is: What can we do to address this? Better docu? Better samples?

ioana-blue commented 8 years ago

I was initially confused by "feed" as well and the relationship between feeds and triggers. I think we could benefit from a better terminology. So maybe we ask for some alternative names.

In my mind, "feed" is a trigger family or a trigger source. Not sure whether this type of names would add to the confusion, though, instead of clarifying things.

rabbah commented 8 years ago

It's called feed, as in web feed. When a wsk user creates a trigger, they can subscribe to a feed such that new content (an event) from the feed results in a trigger activation.

sjfink commented 8 years ago

Attempt 1 at definitions:

an event is something that happens at runtime
a Trigger is a name for a class of events. It is similar to a "topic" in pub-sub systems.
a Feed is an abstraction for a stream of events, all of which belong to a Trigger T. A feed provides lifecycle operations create, delete, pause, and resume, via a whisk action interface. The whisk system can use a feed's action to control the stream of events.

andreasnauerz commented 8 years ago

@rabbah I think we all understand what it is and also the reason why we named it that way. But imho that does not help if a significant amount of users do not get it and that is what the user studies/labs show :(

@ioana-blue I agree, another name may help as well (many users seem to be confused by that term as they do not get the realtion to web feeds) but changing things others already got used too may be dangerous as well (not sure).

@sjfink Even though I understand what you are saying I doubt it will help (gut feeling); maybe explaining along samples may help? Maybe we should make a concrete sample part of the docu and explain the diff between all these concepts? At least me would help that if I would be a user.

I am just thinking out loud, too. What do you guys think?

mbehrendt commented 8 years ago

agree with @nauerz-ibm . while all these definitions are technically accurate, many people are struggling to understand them intuitively -- we should work on some simplification here (not a new topic :-) )

rabbah commented 8 years ago

i'd like to understand why "people are struggling" because there could be many reasons (poor presentation, lack of proper definitions, no intuition given, etc.).

andreasnauerz commented 8 years ago

I can try to get more details. What do you think about using concrete samples to explain the differences between our concepts and how to apply them?

rabbah commented 8 years ago

there are several experiments we can do (perhaps as part of the user studies) to learn from and adapt.

sjfink commented 8 years ago

@nauerz-ibm I agree we should write a doc which shows the definitions along with examples.

mbehrendt commented 8 years ago

i don't think it's lack of proper definitions -- we have them, but they're i think too abstract / not intuitive enough. we should think about a way how to present the definitions in a more tangible / practical way.

the definitions should be 1-2 sentences, shouldn't require detailed examples (while examples are good for further clarification)

rabbah commented 8 years ago

to @mbehrendt's point, we might need some examples to accompany the definitions (or analogies to RSS feeds for example - among others). this is why understanding what the issue really is matters; and more over, there may be gaps to address in the CLI or UI.

andreasnauerz commented 8 years ago

So it seems we have an action plan:

Reword the definitions to make them more intuitive (less "technical" != inaccurate)
Accompany them with some simple samples to deepen understanding (I am not thinking of code samples, of course)

Who volunteers to give this a 1st try? :)

mbehrendt commented 8 years ago

i'll give it a try

julicjung commented 8 years ago

Just chipping in my 2 cents: My understanding of a "feed" in whisk context is roughly "a stream of events". I struggle a little with distinguishing this cleanly from the concept of a trigger and my mind came up with something like "a feed is a kind of configuration when triggers" get fired. Or is it more like an input channel through which my trigger gets repeatedly fired?

When I browsed the docs I never really felt like I found the place to say "Ah, now this is the section where feeds and triggers are explained". E.g. I still do not know I can create my own feed or if I am constrained to the system provided ones. The info may very well be somewhere in the docs - it might just that I did not readily found them this is the entire problem.

rabbah commented 8 years ago

We haven't described yet in the docs how to create your own feed.

mbehrendt commented 8 years ago

what about this, as a first stab for defining terminology? any feedback welcome, pls feel free to throw tomatoes :-)

feed — a feed implements the knowledge for how to setup receiving events from a particular source. for instance, a github feed knows how to setup github webhooks, a cloudant feed knows how to configure cloudant for sending events about data changes.

trigger — a trigger is created to express the interest in a particular event — it specifies all information needed to let the trigger fire whenever an event occurs. triggers are always created based on feeds. for instance, someone might create a trigger for their specific github account, such that the trigger always fires when a new file is committed.

jthomas commented 8 years ago

I struggled to understand the event, trigger, feed dichotomy until I implemented my own feed. As a developer, I associate "feed" with passive data sources, an RSS feed. Looking through the catalogue packages, I discovered the a "feed" is closer to a service broker. It receives lifecycle events for registered triggers, which it can register with an external provider.

csantanapr commented 8 years ago

Related to #559

rabbah commented 8 years ago

@csantanapr @sjfink since this is now merged: https://github.com/openwhisk/openwhisk/blob/master/docs/feeds.md#difference-between-feed-and-trigger

is this issue resolved?

sjfink commented 8 years ago

I'll say yes. Closing.

csantanapr commented 8 years ago

sorry, I forgot to close the issue when I merged. I'm used to github auto closing for me :-) when using Fixes Closes #xxx

apache / openwhisk

Make it easier to understand what a feed is #345