Add a user-friendly iopages including support for Bluemix.

[ddebrunner]

While all the samples exist, there's no nice way of finding one, since there is not a github io pages for the project. Could one be added with a well formatted list of the samples and pointers to them. it some ways this is just a dumping ground for samples, rather than a useful repository.

I'm also wondering if for any samples that can run in Bluemix can we provide a ready built app, so a user can get an instant idea of streaming or the concept the sample is trying to demonstrate.

[natashadsilva]

HI @ddebrunner I am working on this ...see https://natashadsilva.github.io/IBM-Bluemix.github.io/ which is a fork of https://github.com/IBM-Bluemix/IBM-Bluemix.github.io. Please take a look and give your feedback here.

[ddebrunner]

That looks great! :fireworks:

Would we keep all samples on a single page (just wondering how it will behave with many more samples, (e.g. if we linked all in from toolkits and the samples repository) or instead have some pages with smaller sub-collections (e.g. consistent region, beginners, java primitives, etc.). In that case a sample could be in multiple sub-collections. Maybe the filter by tag is sufficient for that?

Is this meta data driven? I.e. how would someone add a sample to the page?

[mikespicer]

Nice, I tried the filters and search and they seem to work pretty well. It looked like the search was on the sample description not the source code. It brought up good results with a number of search terms like windows and operator names. I'm wondering if we should also allow a search of the source code but concerned that may bring in a lot of results that are less relevant. Perhaps a future enhancement could be to allow a search of operators used or all source code.

[natashadsilva]

The Filter tags support samples belonging in multiple categories. The search works on the description and tags (not shown in the page). I am working on script that will scan directories for a "catalog.json", with the idea that adding a sample to the catalog will just involve adding this file and the scan will pick it up and update the page accordingly. The idea is that the script will run nightly or be triggered by check-ins.

@mikespicer I thought about scanning the source code for operator invocations (pretty simple to search for) and adding those to the metadata of a sample. If we decide on a set of less interesting operators (e.g. Customs, Beacons, Throttle) and exclude them, that could be useful.

As for performance, the site is based on JSON which is loaded when the page is loaded and the JSON objects are searched when the Filter or Search actions are used. I tested the page with 1000 samples, so 1000 JSON entries and it didn't weigh down the browser. We have about 150 so far. If it becomes slow or hogs memory or freezes, one option is to use server side JavaScript to serve the data. The downside to this is that the search will have to call out to the server so the searches wouldn't be as fast.

[ddebrunner]

@natashadsilva Did you test 1000 samples on a mobile device as well?

[natashadsilva]

@ddebrunner I went back to working on this and yes, with 1000 samples on a mobile device it took a couple of seconds to load, and then filtering and unfiltering takes a few seconds each time. I am going to experiment with adding a spinner which would remove the impression that the page is hung.

I have moved my changes to a fork of this repository, see them here:https://natashadsilva.github.io/samples/ Each sample folder has a catalog.json file that describes it.
I wrote a script that generates the full json for that page by merging the catalog.json from each sample. Example: https://github.com/natashadsilva/samples/blob/master/ConsistentRegions/NonBlockingCheckpoint/catalog.json Added: -option to filter by Integration points (Edgent, bluemix) -new sticker for featured samples (additional tag added in JSON) -link to sab file (none of the samples have that yet, so its just a dummy demonstrating where it would go) Any additional comments are welcome!

[chanskw]

Can we please: 1) Add interesting links as in the streamsx.tutorial site 2) For categories, I think performance and consistent region should be separated.

[natashadsilva]

@chanskw Done.

[chanskw]

Can we also ask a button that allow user to suggest samples to add to this repository? The button should direct people to open an issue in the samples project.

Can we also please add the water conservation app as one of the samples? Thanks!

[natashadsilva]

@chanskw Can you follow the process to add the water conservation sample? This will help me see if the process is actually meaningful 😄

[jakrmpotic]

@natashadsilva - I've been thinking about how to make it easy for customers to find all the samples for a particular toolkit, based on the assumption that customers want to check out a few samples to help them decide if the toolkit will help them achieve their goals.

We have 24 toolkits that have 1 or more samples each. When I search in the samples catalog for "toolkit" I get a bunch of results, but it's not easy to see what toolkit is associated with which sample.

How about updating the sample catalog tiles to allow users to filter by type of toolkit? See attached screen cap for a mock-up. Also, instead of having one long list of Toolkits in the filter, how about listing the toolkits by type (according to the toolkit categories @chanskw using in a markdown list a few years ago)? I attached another screen cap that shows the 4 lists (based on the toolkit metadata inventory I did a few months ago, which you can find in Box: https://ibm.box.com/s/skabmk8sfl04ytd9fwlxpljk5puilpih ).

[natashadsilva]

Hi Jasna, Thank you for the feedback. The samples catalog does not include the samples that are in the product. Its original purpose was to help organize the samples from published articles. There is value in adding the in-product toolkits to the catalog but it is tricky since those samples aren't hosted on Github so some additional plannning is needed. Until then, adding a search by toolkit might be misleading because not all toolkit samples are present. So the first question is really whether we want to pull in all the product samples and display them here as well, because otherwise search by toolkit is misleading.

but it's not easy to see what toolkit is associated with which sample.

Right now, if a toolkit is used in a sample, it will (typically) appear in the result even if the focus of the sample is a different toolkit. I can see how it would be confusing. Perhaps an "also uses the x" toolkit annotation would be better.

[jakrmpotic]

Thx for the explanation Natasha. RE: "So the first question is really whether we want to pull in all the product samples and display them here as well, because otherwise search by toolkit is misleading."

The catalog would be a great way to publicize the toolkits. As users explore the samples, they might learn about a toolkit and try it out. Most users who explore aren't looking for a particular toolkit, but they are looking for samples that will show them how to do something or how to do something easier.

BTW, I didn't realize the catalog was only for samples from published articles. If I follow the Samples link from http://ibmstreams.github.io/, or go directly to the samples catalog, it's not clear that this is a particular subset of Streams samples.

If you decide to explore this further, and you think it's important to distinguish between samples from toolkits and those from articles, maybe use visual cues on the tiles, like DSX does. For example, every tile has a keyword title

[markheger]

The iopages and the samples catalog are covering samples from this repo and few from other repos.

If product samples shall be visible in public GitHub another issue has to be created for this feature request.