Suggestions for Improving Tour.py

[mtanco]

Reoccuring feedback from new Wave Developers: There are too many examples in documentation (tour), and many of them are too niche or small in functionality to help me get up and coding fast.

Suggestions:

• [x] There should be a hello_world_script (exactly the same as the current hello_world) and a hello_world_app (write in the format of @app)

• [x] None of the apps should use faker - this is our own special library which confuses people. Also, examples that are repeatable are easier to understand so it would be better to have a set dataset to use rather than make a fake one every time. Maybe use fake to created a csv to ship and always use?

• [ ] Notes for all "real" apps (To Do List, Wizard, Issue Tracker, Dashboard)

  • Have a header at the top explaining what the app does
  • Meta card
  • Should only use the app function for routing, all content rendering should be in a single function per view
  • Should not use Faker or synth
  • If cypress is used it needs to have comments explaining what it is and how to use it - probably all of these should have testing
  • Are global variables okay, I thought this was bad practice?
  • I cannot imagine a new to wave person being able to learn from the current dashboard example but I don't have specific solid feedback on how to fix this, it's just... a lot going on!

• [ ] Notes for Widget Examples

  • [ ] Stats Cards

  • [x] 12 current examples should be rolled into one app

  • [ ] Avoid column names like foo and qux as this is hard to internalize

  • [ ] Avoid faker

  • [ ] Layout / Position

  • This should be the first app - explaining the grid I think is really important

  • Should this be rewritten to be responsive, or can we add a responsive version of this?

  • The notes in this example are AWESOME

  • [x] Form (all of them)

  • I like that the current form.py file has everything - i think we should focus on making this really nice and get rid of all of the other Form / Thing. There should be one example that is a form with non-interactive elements and then one form with interactive stuff (Just pick one element, color picker or checkbox or something - people are smart and can use the UI docs to replace if they have one good example to start with)

  • Each element should follow the same format for any text: element name: some example

    • ui.text_xl(content='text_xl: use for headings')

  • Add new lines between different types of conent

  • Do general clean up (like right now all 3 checkboxes have the same name element)

  • Add any important notes (like explain that the name element will be used in q.args when you click the thing)

  • I think if everything is in one function then all the text from html, menu, and spec should be too

  • avoid Faker if possible

• [ ] Tabs.py should be a stand alone example but be re-written to persist the checkboxes using q.client.x (this is how I did this a while back https://github.com/h2oai/sales-engineering/blob/master/mtanco/wave/q_apps/tabs_save_items.py)

• [ ] File_upload.py should be a stand alone example but add how to use the file - show q.site.download and then print the file name and type to the screen (or something)

• [ ] frame_path.py should be a stand alone example and include notes for the newbie about needing the site to be secure to work and also that some sites block you from using them in frames

• [ ] Form_menu.py should be a stanealone app but is currently a bit confusing (to me)

• [ ] Stepper.py should have just one stepper and forward/backward buttons that show how to move though steps

• [x] Table

  • Consolidate all of the Table files into one example with comments that example what is happening
  • Use real data instead of faker (maybe use Faker once to make a permanate fake dataset of Issues, save that as a csv and use that in the example)
  • I think it would be really nice if the data was from a pandas dataframe instead of a list of Issues

• [ ] Image.py and frame.py and frame_path.py can go away - actually I am feeling lazy to write them all, the small example x_card.py files can go away - people can find this in the ui api docs

• [ ] There should be a data buffer teaching example with a lot of comments

• [ ] Nav.py should be rewritten to be an app that uses navigation, so when you click each section some other page is updated

• [ ] Toolbar.py can someone take the time to make this be a real app? I think that would really help people see how functionality works (like if hte upload share and downlaod buttons actually did something)

• [x] Native Plots There should be one file that does 4 intersting plots, explains how data works etc. just 4. the 20+ is scary to people

  • plot_area_line_groups.py is really pretty and histogram would be good to *Don't use Faker if possible

• [ ] Third party plots:

  • there should be one app that puts each of these in their own card. Just one from each library

• [ ] I think the broadcast / multicast can stay in the documentation rather than be in the example, unless there's something special to show here

@lo5 as per our conversation I will let you, @mturoci, @VijithaEkanayake, and @dulajra actually make these changes. But this is what I would do if I were to take a stab at this project

@LenaRampula and @meganjkurka please review as I know you have thoughts on this too!

[LenaRampula]

TODO For Faker: Issue Tracker, Dashboard, and Stats. Stats will be updated after #370 will be merged.

Issue Tracker and Dashboard require some more thought.

[geomodular]

Related issues https://github.com/h2oai/wave/issues/280 https://github.com/h2oai/wave/issues/31

[LenaRampula]

@mtanco @lo5 I went through the third-party plots trying to put them all in one example. It becomes way too complicated. Each example has its own dependencies and the examples for each type are quite long.

I suggest we leave the third party plots for now. Maybe just renaming from "Plot / Library" for better readability.

We can merge the vegalite examples into one.

None of the third party examples use fake data. But the altair example uses vega_datasets. Maybe we could replace it with the data used for native plots.

Let me know what you think.

[LenaRampula]

@mtanco @lo5

Image.py and frame.py and frame_path.py can go away - actually I am feeling lazy to write them all, the small example x_card.py files can go away - people can find this in the ui api docs

I think we should keep those. frame.py and frame_path.py can be in one example. image.py needs a better explanation for the required format. I had to struggle a bit to get an existing png into the right form.

We could also combine all the text display examples into one: text, markdown, header, label, link, markup, separator.

[lo5]

@mtanco @LenaRampula

I don't see any reason why multiple examples need to be combined into one.

The examples were separate for a reason: we don't want users to have to go through 200 lines of code just to figure out how to use a single component.

For example, the individual stats cards combined is similar to dashboard.py (which demonstrate how to use them together), but they each have their individual examples as well so that we can cover their nuances.

If the problem is that the examples themselves are poor, then we should try to fix the individual examples.

In general, we have to address this on three fronts:

1. Tour - Demonstration of techniques: super-short examples that show a bit of code and what the end result looks like.
2. Wave Apps: Demonstrate how to weave cards/components together to make complete apps.
3. Kitchen Sink: We're working on this to be an exhaustive display of what is capable in Wave visually (e.g. all cards, all components, all kinds of layouts) - to demonstrate the breadth of capabilities in the front-end.

[lo5]

@LenaRampula - Thanks for the PRs!

How do you think should we proceed with #387 #383 #381 and #374? I'll not be merging those PRs directly, mainly for the reason I stated above - they remove the short examples and replace them with larger examples.

Instead, it's preferable to:

• Improve the short example, if necessary.
• If Faker needs to be replaced, replace it with curated data, not just the raw output of Faker (seeing the gibberish sentences in code, for example, seem distracting to me).
• Add a new example demonstrating a specific technique.

In all cases, having several, short PRs that address specific concerns is preferable to those four - they'll get merged quickly.

[LenaRampula]

@lo5 Here is how I was thinking about it: We have about 180 examples. It's very difficult to orient in them. Some of the examples are complex and some are very simple with only one parameter differentiating one example from another. The short examples that specifically describe single components could be very helpful in the API reference (similar to Pandas docs). Those examples could be limited to the use of a single component without the whole app definition. In the examples sections, I would find it more useful to have a handful of more condense examples that solve a specific area: Text, Table, Plots, Navigation, etc. They don't need to cover everything that is available but to give a new user an idea of where they could start. They could copy the code and adjust it to their needs.

If you absolutely disagree that we need to decrease the number of examples we need at the very least:

• Replace Faker and Synth with simple data frames
• Add comments in the code
• Consider renaming the titles of the examples and introduce a hierarchy - e.g. all the plots under one expander
• Avoid using structures that may confuse an average python user (e.g. ${{intl qux minimum_fraction_digits=2 maximum_fraction_digits=2}}')

[lo5]

From your comments, PRs and the original issue above:

I don't understand the motivation behind "There are too many examples", "It's very difficult to orient in them." and "the 20+ is scary to people". I think we need more examples, not less, especially for data visualizations, where it's next to impossible to find a code snippet for what you need using the name or description of the example - it's way easier to scroll through a gallery of pictures of visualizations, find one, then tweak from there.

If anything, we need more examples. Our Q1/Q2 roadmap has an additional 150+ cards and components. We don't expect users to browse through the docs menu to find examples. If "there are too many examples" really means "it's too difficult to find/navigate examples", there are other ways to solve it (instead of merging examples into bigger files):

• Enable search (#309 is already in progress).
• Improve each example like I mentioned above (add keywords, descriptions, comments).
• Add an additional cover page (parallel to the Gallery page) that groups and links all the examples in a hierarchical/descriptive fashion.

Search can also solve the problem of "how can I easily figure out how to do X".

I would find it more useful to have a handful of more condense examples that solve a specific area...

We'd be happy to accept PRs for new examples and tutorials. The current list of tutorials and examples is by no means complete, and we have to continue improving them over time.

Replace Faker and Synth with simple data frames

31 was already planned, and predates this issue. It takes time and effort to think of real-world datasets and variable names to suit each example.

I wrote synth.py to generate realistic-looking time-series data for demo'ing our realtime vis use cases. I'd love to see a counter-proposal that preserves that behavior. We can add new examples that show hard-coded data - PRs welcome.

Faker and metasyntactic variables are a quick way to push new examples out when we get asked by app authors "how do I do X". We know they're not ideal, and we do this with the understanding that we will improve them when we have time. If you have better ideas, we'd love to have PRs with improved examples.

Add comments in the code

So like I said above, PRs for improving our current examples (without merging/combining) are more than welcome.

Consider renaming the titles of the examples and introduce a hierarchy

Good suggestion.

Avoid using structures that may confuse an average python user (e.g. ${{intl qux minimum_fraction_digits=2 maximum_fraction_digits=2}}')

I'd love to see a counter proposal to the data-binding and internationalization API that will solve the same problem more elegantly.

[LenaRampula]

I don't understand the motivation behind "There are too many examples"

The feedback is mainly for the difficulty to get started. The list of examples doesn't help me understand how to use the components. Hierarchy and better naming could help. I guess the question is, can a new user find what they are looking for? Can they easily adopt the code? The gallery is nice but when you have 3 examples on Tabs, for example, it's hard to understand which one you should use.

I guess I got used to expecting the examples to follow the API reference. This way I can skim through the definition and see what is required, and then copy the code at the end of the reference.

We'd be happy to accept PRs for new examples and tutorials. The current list of tutorials and examples is by no means complete, and we have to continue improving them over time.

Would you like to add tutorials that go through the native plots, text options, navigation options, a selection of basic cards to start with (something like: "the first cards to master"). I think I could adapt the work done till now to put something together.

It takes time and effort to think of real-world datasets and variable names to suit each example.

I think it's more important for the user to understand the required data structure than having "real" data. It is preferable the examples could be used as-is (not depending on the examples directory for synth.py or on an external library like Faker). And a hard coded data frame cannot be huge. I can improve the data I used in native_plot.py to be more real-like and create new PRs for replacing those in each of the examples separately.

I'd love to see a counter proposal to the data-binding and internationalization API that will solve the same problem more elegantly.

I'm not sure what that means. I never saw this syntax before, and I'm not sure if there is a more pythonic way to do it. I would guess I'm not the only one who would not be familiar with it. If there is no other way to do it, it would be great to explain it in a comment.

I'll close my PRs, as they are not going to be merged. If you'll agree with the tutorial suggestions, I'll create new PRs for those. If you are ok with real looking small data frame to replace synth and faker, I can do this.

[surenH2oai]

@LenaRampula if you are looking for good starter sample/example wave applications you can find them here https://github.com/h2oai/wave-apps. You can also work with @mtanco and the wave sample application team to come up with more sample apps or ideas.

As per "examples"/tour, https://h2oai.github.io/wave/docs/examples The more the better for all possible UI Elements because the goal of these examples is for a python developer to easily understand how to use these components, not to teach them python nor teach them how to develop "client server web application", which is done through the sample OSS wave applications we have made available via "wave-apps" in a public repo.

The team has been working super hard to meet the Q4 deliverables both on WAVE SDK and WAVE Cloud side of things. There is lot to do but very limited time, the team is prioritizing most important features need to be delivered in the most efficient way possible.

For more concise feedbacks and to find the roadmap of WAVE, please feel free to setup quick sync with the team over zoom/slack is more efficient than via Github.

[mtanco]

Perhaps this will change with wave-apps (although some of these should probably be simplified some) and search, but almost every single person internally who has built their first wave app has been overwhelmed by the examples and did not know where to start or how to find what they needed or when to choose one of multiple options (like tabs for example where there are 3 different examples). There are many questions in #wave that say things like " I am copying tabs but how do I save the data" or people ask a question that is answered by and example and they say "oh I couldn't find that thanks!" or they explicitly say "There were a lot of examples and I didn't know how to find what I needed"

So this issue was specifically around: how do we make your first week Wave developing easier.

Would we agree that to start we could:

• [ ] Add header comments or further notes that explain what each example does
• [ ] Add inline comments
• [ ] Group examples under sub-headers (instead of grouping in a file) so that when you open examples you don't have 100s to look through but you can quickly orient on what you need like: Type of Cards, Plotting Data, App Navigation. That type of thing ?

(and #31 which is already and issue).

[lo5]

This discussion has too many fleeting generalizations. We need specifics.

Different people have different experiences getting started based on prior experience or skills, so attempting to represent the "average Python user" is not productive. We have 60+ apps already, and there's plenty of evidence that once you grok the mental model, your productivity skyrockets - we regularly see folks turning around with new apps in hours. We'll be producing video tutorials and walkthroughs in 2021 that will ease the getting started experience - we just haven't had time to do it.

Instead of continuing the discussion, let's do what we've always been doing:

1. Identify one small aspect of the individual docs pages or examples that bothers you. If you can fix it, send us a PR, and we'll be happy to merge. If not, file an issue: "it's not clear to me why ", "how can I do ?", etc., and the team will happily address it.
2. Repeat.

Thanks in advance!