Teal development guide

[asbates]

Write a guide for people wanting to learn about developing apps with Teal. (question from R Consortium webinar)

[pawelru]

There is a contributor guide already. Isn't it enough?

[lcd2yyz]

I think it may be referring to a technical developer's guide?

[pawelru]

learn about developing apps with Teal

It's a broad term and I believe this will be completed via multiple other issues:

• https://github.com/insightsengineering/coredev-tasks/issues/465 -> deprecate internal dev-guide and move relevant parts into the contributior guide linked above
• https://github.com/insightsengineering/coredev-tasks/issues/467 -> publicise internal teal blueprint
• Teal Training Materials nestdevs-tasks#16 -> teal training materials including "how to" series

[asbates]

This refers to a guide the help people build teal applications (vs. working on the teal packages). Like a compliment to teal gallery but instead of just saying 'here's the code,' explain the code, additional features not covered by teal gallery examples, etc. The idea was to start with some basic examples, build up to more complex examples, all the while explaining what is going on.

It's very difficult to look at the vignettes and teal gallery examples and really understand the core concepts of teal, even for experienced developers. The relationship of packages are complex and it's often not clear what each package does and how it relates to the others. This guide is meant to close that gap.

[chlebowa]

Has this been solved by the "blueprint"?

[donyunardi]

To some extent, yes, since blueprint give a high-level introduction on how teal works.

I believe what @asbates is recommending is a step-by-step tutorials on how to build a teal app, specifically tailored for Teal app developer actors where at the end of the tutorial, user can produce the same result in the tutorials.

Perhaps something like:

Tutorial: Writing your first teal app!

In this tutorial, we will create a teal app using a non-cdisc data (iris and mtcars) using a module from teal.modules.general.

Step 1. check if you have install teal frameworks and teal.modules.general
(content to shot some code to check your teal versions)

Step 2. call your init function
(content to explain why we're calling the init function)

Step 3. use the data= argument, explain what to do with your data.frame (use teal_data() and dataset(), and explain why).
(we do have vignettes explaining these functions/constructors, so just high-level explanation)

[asbates]

To some extent, yes, since blueprint give a high-level introduction on how teal works.

I believe what @asbates is recommending is a step-by-step tutorials on how to build a teal app, specifically tailored for Teal app developer actors where at the end of the tutorial, user can produce the same result in the tutorials.

Perhaps something like:
...

Yes, exactly. The technical blueprint looks great and I'm sure it's super helpful for those developing Teal itself (and potentially some power users). What I was thinking of here though is assuming I know nothing about Teal, how do I develop an app? Even for people experienced with Shiny, there is a learning curve with Teal. I'm suggesting to help flatten the learning curve.

One of the first things on the README for example is a list of the Teal building block packages. As a brand new user, do I need to know all of these? Should I go through and read all the vignettes? In what order? What are the must-know packages and what aren't? If I had a guide that started with assuming zero knowledge and gradually built up to more complex examples and more concepts, I wouldn't need to ask those questions. To be clear I'm not suggesting a completely comprehensive guide. But something to get people started and to teach them about building apps without them having to navigate all the docs of all the packages and try to figure it out themselves.

There is the gallery of course and that's great for a reference. But it's essentially a code dump and there's not much context. Some people don't learn well or quickly from a bunch of code with no context. I typically don't do well in that approach for example. If I wanted to build Teal apps and that's all that was available, I may not even want to start.

The package documentation and vignettes have improved also which is awesome. But I find these lacking context as well. Teal has a lot of concepts and terminology that for the most part the docs assume you already know. Not to mention concepts overlapping with Shiny like modules. I find the documentation to be more of a reference rather than learning material per se.

Ultimately whether something like this gets added doesn't affect me because I don't really make Teal apps and my stint on the team is enough to where I could start making Teal apps if needed. But I do remember how confusing things were when I started and I don't think I'm alone in that. Right now users basically get an information dump, much of which isn't relevant to them. When I come across things like that I tend to pass right on by. I'm pretty sure a lot of other people would too. So really I see this as an adoption issue. I think if you want more people to use Teal (and you should, it's great!) then it would help to have some learning material vs. reference material.

[asbates]

And I think there already is some material. I know @donyunardi has done workshops. Maybe some of that can be repurposed and compiled together?

[chlebowa]

Very well, I share the sentiment.

This should probably be in before we release on CRAN.

[lcd2yyz]

Few ideas that should be easy/quick to achieve to begin

• Add link to teal README pointing to various past workshop recordings
• There is a small group from Roche currently developing contents for a Coursera course on clinical trial data analysis. One of the course module will be on how to build teal apps. Once that's ready, we can share the course slide deck and/or course recording via teal/NEST website (assuming no legal/copyright issues).

It would take more efforts however, to develop a written guide. But there may be users preferring this option as well. So maybe something more robust like this

[chlebowa]

Linking to other materials is not a bad idea but incorporating it may feel overwhelming. The guide should be brief and self-contained.

[donyunardi]

We should include topic around shiny module (i.e. Tutorials: Write your first teal module!).
In this tutorial, we can cover the topic around qenv and reporter.

[chlebowa]

That is thoroughly covered in a teal vignette already.

[donyunardi]

We created a video tutorial on teal framework that discuss in detail on teal components, including on how to write a custom module:
https://www.youtube.com/watch?v=N8ZamECICSI

Please check it out and I think this should fulfill the requirement for this issue.

[chlebowa]

Overall the video is stellar work ⭐
I do have some nitpicks, however:

@ 13:26: "Note that all modules are not compatible with this data format"
This should be "(...) not all modules (...)". There is quite a difference.

@ 19:40

This is not crucial but ideally the server code should read

teal_data() |> within({
  MTCARS <- head(mtcars)
})

like in previous examples using within.

Also, it is mentioned in the description but people often don't read descriptions, so I think it wouldn't hurt to say in the video or display on-screen text that the video is an abridgement of the vignettes, i.e. there is nothing here that one couldn't have read already. It may save someone half an hour.

---

Again, great job @vedhav 👌

[vedhav]

Thanks Aleks! So happy to see you from the other side!
AleksGPT was unable to review this before publishing 🙈 Perhaps next time it will be an open review. I hope there will be some content with teal transform when we make that big change.
Yeah, I would have liked to lint the within code properly. It was made because it was easy to showcase the ... args of within. So all the code is in one line and args in another line.

Ideally, I was aiming for this:

teal_data() |>
  within({
     MTCARS <- head(mtcars, n = rows)
  },
  rows = input$rows
)

But, too many lines. So it was this (Not a valid lint either auto lint will make it worse):

teal_data() |> within({
        MTCARS <- head(mtcars, n = rows)
    }, rows = input$rows
 )

teal_data() |> within({
        MTCARS <- head(mtcars, n = rows)
    },
    rows = input$rows)

Or this, relatively I felt this is better for showing the code and params in different lines without distraction:

teal_data() |>
  within(
    { MTCARS <- head(mtcars, n = rows) },
    rows = input$rows
  )