Creating teal user guides

[lcd2yyz]

As teal continue to expand in audience, teal app users are becoming more diverse, which may include stakeholders who are not accustomed in using interactive data visualization tools. Therefore, some general "how to use" type of user guides in helping to orient app users, providing an overview of all the possible features, or brief explanation of the UI buttons, will be very valuable resource.

Initial ideas on potential formats of the user guides

• Video tutorial of example teal apps
• Introduction slides, with annotation on key features or main UIs
• Vignette-like documents (eg. no codes, just lots of screenshots with explanations)?

Potential contents to covers

• General layouts of teal app - which section for what
• Teal behavior - eg. filter/subset input data on right-hand-side panel, change settings of analysis/visualization on left-hand-side panel
• Filter panel
  • all the different filters and what they mean, what behavior to expect (eg. drag slider or enter range for numerical filters)
  • how to use snapshot manager
  • how to read/interpret module-specific filters
• Various features of teal widgets
• Reporting feature
  • from each module how to add analysis
  • from reporter tab, how to organize contents and general outputs

Feel free to add more ideas or contents of interest

[chlebowa]

Many (most?) of the proposed topics seem to be covered by the Technical Blueprint vignettes.

[lcd2yyz]

The intended audience of this user guide are not shiny developer or even app developers, so the technical blueprint vignettes are mostly non-relevant here. Target audience are the true app users - stakeholders that interact with the app to view analytical results. These users may not be familiar with the input data, may not understand and not interested in learning about the technical blueprint of the product. Rather they just want to be able to use the app to get results. So we need to lower the bar to help them understand where things are, and what each button/UI do. Something like this but hopefully ours can be more elaborate.

[vedhav]

@lcd2yyz What do you think about implementing cicerone to create guided tours instead of documenting about this extensively? I see a risk of a teal user getting overwhelmed by all the docs we have if we keep them close to each other. Often times finding these docs is harder and having the docs within the app is a good solution for this. But, I think the bigger question here is that we need to redesign teal to be more user-friendly so extensive user docs are not needed. I believe cicerone is a step in the right direction and hopefully, after some UX design reviews, we can improve it further.

One more argument is that I can still see a completely new user still alienated from teal app features because apart from the common teal app features like the filter panel we will not be able to create extensive docs for all the encodings available in the teal module packages. Cicerone could be extended to modules as well for a better UX and onboard people do actionable things, I can also see a future where we create a widget for this and allow the app developer to modify the help-texts if they want, perhaps specify some study specific information that might be easier for the app user to understand.

[vedhav]

I do see benefits of a vignette like "How to use teal" which would be similar to the getting started vignette but strictly from a usage perspective. In the video that I am making I did not dive deep into how to use all the features of teal but it's closely linked with this as you mentioned on Slack. I think the doc form of that video can be made into this vignette. But, I would like this to be very-short and concise like a cheatsheet pdf with lot of graphics and information delivered. Ideally, one feature explained with just one screenshot (with annotations and graphics) for it to be valuable.

[lcd2yyz]

I would like this to be very-short and concise like a cheatsheet pdf with lot of graphics and information delivered. Ideally, one feature explained with just one screenshot (with annotations and graphics) for it to be valuable.

Yes exactly!

What do you think about implementing cicerone to create guided tours

I'm not familiar with the package itself, but it seems very similar to those "WalkMeThrough" widgets, very neat. I've actually implemented something like it for a shiny-dashboard product previously, that we called "app tour", where users can choose to enable or disable the app tour as part of help function (I can share more info via Slack as it's an internal app).

This looks to be a very promising long-term solution, but obviously will also take more time/efforts to implement at first. So I would consider still create the "how to use" guides/video as a lower-hanging fruit to get the material to users quicker. Once we have a good coverage of the basic material, we can switch gear to develop these types of interactive help features, that can be more robust, comprehensive and easier to maintain.

[chlebowa]

@vedhav Note that encodings are part of modules, not teal itself. teal provides only the module tabs, header/footer and, optionally, the filter panel. Module content is not teal. While having a brief explanation of modules would be nice, it should be part of the module, not teal. We could possibly build an "exlpain module" feature that will be placed directly in teal that will view the explanation for the currently active module.

[donyunardi]

To reiterate, the goal of this issue is to create content aimed at app users on how to use the teal app. We can format the content as a PDF, making it easy to edit and share with both internal and external teal app users.

[kumamiao]

Please also involve my in this one, will be happy to provide some examples that are more focused on clinical trial usage. Let's aim to create the guide to audience who do not program.

[donyunardi]

Considering the UI/UX changes that we're going to apply soon, should we postpone this? @kumamiao