Placing actors badge in every function document so it's easier to focus on certain functions/methods

[vedhav]

Similar to the lifecycle::badge we can introduce a custom actor_badge() which we can add inside each function/method so it becomes very clear for actors of a group to focus on the functions/methods that are relevant to them without getting sidetracked.

The idea is to add a Teal App Developer and Teal Module Developer badges that will redirect to the actor's vignettes when clicked on.

We can have a simple helper function to help us add this to the roxygen comments:

#' Adds the teal actor's badge
#'
#' Usage: `r actor_badge("teal-app-developer")`  `r actor_badge("teal-module-developer")`
actor_badge <- function(actor) {
  url <- paste0(
    "https://insightsengineering.github.io/teal/latest-tag/articles/blueprint/actors.html#",
    actor
  )
  html <- sprintf(
    "\\href{%s}{\\figure{%s}{options: alt='[%s]'}}",
    url, file.path(sprintf("actor-%s.svg", actor)), actor
  )
  text <- sprintf("\\strong{[%s]}", actor)
  sprintf("\\ifelse{html}{%s}{%s}", html, text)
}

[lcd2yyz]

I'm all for better categorization for our documents, so thanks for voicing the idea! But I'm not so sure if it will help meaningfully, rather than becoming a distraction or stagnant label.

To begin with, user would need to familiarize themselves with the differentiation between "teal app developer" vs "teal module developer" - it's one word difference, and at the same time, the tag with the string "module" is not actually for those who wants to use module 😂 So for new users or beginners, they'll probably have to do a double-take.

Also, I feel the separation should be quite obvious already. Typical teal app developers will work with all tm_xxx functions from all modules pkgs, plus a few ones from teal itself. Then only advanced users and module develops will need to look beyond them, to all other exported functions in any of the teal framework pkgs. The line where one goes from one role to the other feels pretty clear.

Would you have some examples where a function might be ambiguous of its intended usage, for which such actor's badge might help?

[vedhav]

I see your point that Teal app developers will stick to using the functions from teal and module functions named tm_xxx so I agree these badges do not make sense when we add them to the teal or teal.modules.xxx packages. But, I can see how a teal app developer can find it hard to find the limited set of functions that they need to learn to use in the package like teal.data or teal.slice. We mention these packages on the front page of our teal vignettes so people can easily start exploring them and get lost.

If we consider the teal.data package which is also something a Teal app developer will have to use to construct the teal data object which will have to be used inside the data argument of teal::init. And I think this badge in the functions reference page of teal.data would be super helpful for them.

Similarly teal.slice::teal_slice is pretty much the only function that an app developer needs to know about from the teal.slice package and there is also a teal::teal_slices function which only increases the confusion (but it's a topic for another thread)

[chlebowa]

Module developers create modules, not use them. When they do, they become module users, i.e. app developers. I think the distinction is valid. It's not about ambiguity, it's about stumbling on a help page and clearly knowing whether it's meant for you. App developers need not know about qenv but they should know about teal_data. This may soon change but still.

Some pages would get several labels, e.g. ggplot2_args.

I would also add Core Developer myself.

But, I can see how a teal app developer can find it hard to find the limited set of functions that they need to learn to use in the package like teal.data or teal.slice. We mention these packages on the front page of our teal vignettes so people can easily start exploring them and get lost.

I believe this is what the "blueprint" is for.

---

My gripe with this idea is the necessity to tag every single help page.