Onboarding and User Experience Guidelines

[kerrishotts]

Onboarding and User Experience

Hi all! While you’re getting everything ready for submission to the plugin manager, it seemed a good idea to share some of our thoughts around onboarding and user experience with plugins — especially for new users. Most of these are suggestions and ideas, and not all of them will make sense for your plugin.

First Launch Experience

All Plugins

The following are expected experiences for all plugins, regardless of complexity:

• Don’t Fail Silently

  • Plugins shouldn’t fail silently when the user has gone outside of the expected workflow. Instead, display an error message, giving clear instructions on what the plugin expects (and why). If you have a GIF recording of actually doing some steps, that’s even better!

    

  • Consider if your plugin can work outside of the expected workflow. For example, a stock photo search plugin might expect a rectangle to be selected so that it can fill the rectangle with the selected photo. But instead of failing if no rectangle is selected, perhaps the plugin could create a new rectangle instead and fill it with a selected image.

• Handle Edge Cases
  • Related to Don’t Fail Silently, make sure that you consider edge cases that your plugin may encounter. For instance:
    • Unexpected objects in the selection.
    • Don’t assume that there is always an artboard in the document, or that there is only one.
    • No selection at all.
    • Unexpected types of fills (such as gradients or images).
    • Unexpected I/O errors (network or file) — such as out of disk space or no route to host.
• User Support
  • Have some form of “About” or “How to use” in your plugin. How you expose this will depend on how much UI your plugin has, and how much information is required.
  • For a plugin with submenus, “About” / “How to use” could be a submenu that displays a dialog with some text. If you need to display a lot of information, the about dialog could just link to your website’s support material.
  • For plugins that display configuration settings, “About” or “How to use” could be displayed in the corner of the dialog somewhere… perhaps even as a (?) icon. This could also link to your support website, or display some help material within the dialog.
  • For plugins that won’t display UI unless there’s an error, consider adding the support / how-to-use links to your error dialog.

Complex Plugins

• Wizards

  • If your plugin is complex, consider using a step-by-step GIF/wizard in your plugin. Could be at first-launch, or via a (?) icon or menu item.

    

  • GIFs can be really useful in illustrating how the plugin expects to be used.

  • Allow onboarding to be skipped if the user is already familiar with the project.

  • Allow the user to review onboarding again at a later date.

General UX Suggestions

• UI:

  • Use tooltips so that users don’t have to guess the meanings of icons in your UI.

    

  • Be sure your dialog properly handles ESC and ENTER. (ESC handling is changing in the next drop, so heads-up!)

  • Don’t use subsequent dialogs as a wizard. But if you need to display an error message, or invoke your plugin after an auth attempt, that’s fine. (UWP issues are fixed in version 13.)

  • If your plugin handles authentication, make sure there’s a way for the user to log back out without deleting your associated plugin_settings folder.

  • Always have a way out of a dialog — especially auth or other polling-type dialogs. Just in case the network goes down, the user needs a way out.

• Menus:
  • Use submenus when you have multiple related actions
  • Menu items that trigger actions should read like actions — that is, use verbs to demonstrate their effect. For example:
    • Do use “Import data from CSV…”
    • Don’t use “Spreadsheet importer”
    • Do use “Insert photo from Adobe Stock…”,
    • Don’t use “Adobe Stock Photo Search”.
  • Menu items that need more information from the end user (i.e., that trigger configuration dialogs) should have ellipses. For example, “Apply padding to selection…” (where a subsequent dialog is rendered.) Errors and such don’t count, so if your plugin has no UI or will only generate error/success messages, no need for ellipses.
  • When launching a web browser from a plugin menu item, use ellipses in the menu item name. Ex: “Manage Public Links…”
  • Watch your menu name length! Windows is especially brutal here with truncation.
  • Add keyboard shortcuts (Available in v13)
  • Ideally your menu item should be obvious that it’s tied to your plugin. For submenus, this can mean using your branding, but if it’s a top-level menu item, this can be a little harder to do. Keep in mind that plugins that use the same top-level menu items can be hard to tell apart.

Of course, if you have any questions, please ask! The above are mostly suggestions, but we just wanted to pass along some of our thoughts based on our own internal experiences building and testing plugins.