Skip to content

Latest commit

 

History

History
185 lines (137 loc) · 13.4 KB

SCOOBE.md

File metadata and controls

185 lines (137 loc) · 13.4 KB
Raw

PowerToys SCOOBE Dialog

  • What is it: Post-upgrade prompted dialog that walks users through the latest additions to PowerToys utilities and functionalities
  • Author: Deondre Davis
  • Spec Status: Draft

1. Overview

1.1. Executive Summary

To expand on our end-user onboarding efforts, we seek to resolve the critical issue of informing users of new additions and improvements to PowerToys during upgrade scenarios. We currently list release notes on the main repository, in addition to affiliated information on Microsoft Docs. However, neither of these mediums are internal to the application, and thus requires users to proactively seek out information on what's been updated, or merely notice by chance what's been changed from their regular usage. As these are not ideal experiences, this document describes the inclusion of a post-upgrade 'SCOOBE' prompt that launches the previously developed OOBE dialog loaded with new information related to upgrade improvements and additions.

1.2. Key-Definitions/Concepts

Here are definitions for words and acronyms found throughout this document to ensure clarity:

  • OOBE: Out of box experience – The users' initial interactions with the product immediately after installing the product and/or launching the product for the first time.
  • SCOOBE: Second chance out of box experience - The users' initial interactions with the product immediately after upgrading the product and/or launching the product for the first time after upgrading.

1.3. Goals and Non-Goals

Goals:

  • Create a guided prompt that exposes the user to a brief overview of the new features and/or improvements included with the latest version of PowerToys.

Non-Goals:

  • Present a copy-and-paste replica of the repository release notes. This information needs to be readily consumable, often requiring visual demonstrations of the new behavior and/or functionality that's either not possible or not necessary to depict on the repository release notes.

2. Definition of Success

2.1. Customers

The PowerToys SCOOBE is for existing and new power users and developers who are looking to tune and streamline their Windows experience for greater productivity and enhanced user experience. As the PowerToys customer base tends to be particularly biased against SCOOBE prompts in general, we need to present the PowerToys SCOOBE dialog in such a way that it provides immediate value to end-users to improve the likelihood of users discovering all the additions to PowerToys by making their way through the prompt.

2.2. Expected Impact: Customer, and Technology Outcomes

  • High Reliability : Less than 0.1% crash rate.
  • Increased Activation : 50% or more adoption rate of new feature/utilities among PowerToys users who already utilize associated tools.
  • High User Retention: 25% or more active PowerToys users after 28 days of upgrade.

3. Requirements

The SCOOBE dialog builds off the currently implemented OOBE dialog originally drafted by Niel's mock-up.

3.1. Functional Requirements

3.1.1. Functional Requirements Overview

No. Requirement Pri
1. The SCOOBE dialog should launch immediately after PowerToys is updated. P0
2. The SCOOBE dialog should be contained inside the existing OOBE Dialog under its own "What's New" page of the dialog window. See figure 5.1.1. P0
3. The content for the SCOOBE dialog should be stored externally from the PowerToys application. * P0
4. When the "What's New" page is opened, the content displayed should by loaded dynamically from the relevant information contained in the external storage described in 3.1.1.3 above. Assumes the user's device is connected to the internet. P0
5. The SCOOBE dialog should display information on updates that have occurred between the previous version of PowerToys the user had installed, and the current version of PowerToys the user has updated to. ** P0
6. If PowerToys was installed for the first time, the SCOOBE dialog should only display information on updates that have occurred with the version of PowerToys the user has installed. P0
7. If PowerToys was installed for the first time, the OOBE's "Welcome to PowerToys" page should display first, not the SCOOBE's "What's New" page. See figure 5.1.2. P0
8. The structure of the SCOOBE dialog page's content should follow the guidelines described in section 3.1.2. P0
9. After SCOOBE is initially viewed, the user should be able to re-access the SCOOBE dialog at any time by opening the OOBE window again and selecting the "What's New" page. P1

* - By storing the content for SCOOBE externally from the application, the PowerToys team can update/adjust information without being constrained to PowerToys' release cycles. This is critical in the event of errors or miscommunications that would otherwise be difficult, if not impossible, to correct if stored locally to the app and shipped with the version of PowerToys being released.

** - It is important to call out the nuances of potential upgrade scenarios here. If a user upgraded from v0.31 to v0.33, the updates displayed would include only what was changed in v0.33, as this scenario only adds a single release's changes. Should a user have upgraded from v0.29 -> v0.33, the updates displayed would include what was changed in both v0.31 and v0.33 as this scenario involves multiple releases' changes. If the latest version of PowerToys is v0.35 (for example), but the user only updates from v0.31 to v0.33, the displayed information should not include information related to v0.35 updates, as those changes have not yet been added on the version of PowerToys the user has installed. Section 5.1.3 gives textual examples of what various scenarios would look like, with section 3.1.2 describing the page's content layout.

3.1.2. Page Content

No. Requirement Pri
1. The SCOOBE dialog should display the version of PowerToys the user has installed, as shown in figures 5.1.1. P0
2. The SCOOBE dialog information should be grouped into two sections: "New Features & Improvements" and "Bugfixes Highlights". P0
3. The "New Features & Improvements" section should contain information related to end user functionality that has been added or updated. P0
4. The "New Features & Improvements" section should be subdivided by the relevant utilities updated (i.e. Color Picker, FancyZones, etc.). See figure 5.1.1 and section 5.1.3 for examples. P1
5. The "Bugfixes Highlights" section should contain information related to noteworthy issues/errors that were corrected. P0
6. If there are relevant visuals, they should be included with the information text. See figure 5.1.1. P1
7. For multi-version updates (i.e. v0.29 to v0.35), combine the information from each version's updates and display them as a single "New Features & Improvements" section and "Bugfixes Highlights" section. See section 5.1.3 for an example. P0
8. The SCOOBE dialog should be scrollable if needed to fit all the content. P0
10. The bottom of the SCOOBE dialog should include a link to the PowerToys releases page for a complete list of versions and their release notes (Releases · microsoft/PowerToys (github.com)). P1

3.2. Open Discussion

  • How do we localize content like keystrokes and visuals?

  • How do we make keystrokes/activation phrases stand out?

  • How do we handle displaying information for scenarios where a user is updating over multiple versions (ex. v0.29 -> v0.35) for which a change was made but later regressed/altered. For instance, a new FancyZones UX update in v0.31, that was again changed in v0.35?

  • Should we store SCOOBE information for all versions of PowerToys? If not, how far back should we maintain information?

4. Measure Requirements

No. Requirement Implication Pri
1. Date/Time of first-run following upgrade Helps to categorize usage and retention trends across users who've been exposed to SCOOBE. P0
2. SCOOBE section viewed Used to measure activation of the SCOOBE dialog. Should be 100% for the current version of PowerToys following SCOOBE's inclusion. P0
3. Accesses to linked documentation Used to gauge interest in user's desire to learn more about the PowerToys described. P1
4. Access to linked settings pages Used to gauge whether the settings presented to users in the dialog are sufficient for user needs. P1
5. PowerToys launched while SCOOBE window is active Used to track user engagement with the various PowerToys while exploring the content in the SCOOBE. P1
6. Screen size Gives crucial information for considerations related to minimal/maximum window size needed for displaying content. P2

5. Appendix

5.1. Mock-ups

5.1.1. SCOOBE Dialog Layout

5.1.2. OOBE Welcome Page

5.1.3. Example Textual Descriptions for Updates

v0.29 -> v0.31:

  • New Features & Improvements
    • FancyZones
      • Dark mode for the editor
      • Certain settings (e.g. number of zones, spacing settings) can now be set on individual layouts.
    • PowerToys Run
      • Service management plugin (Start, stop, …)
      • Registry key plugin
      • System action plugin (Reboot, lock, ...)
  • Bugfixes Highlights
    • Fixed OneDrive SVG Bug (#9999)
    • SVG are scaled appropriately when view box is provided (#9999)

v0.31 -> v0.33:

  • New Features & Improvements
    • General
      • Added a 'First time load' experience. The hope is a quick, light way to learn about basic functionality
    • FancyZones
      • New options to change zone activation algorithm
    • PowerToys Run
      • Plugin Manager now is in settings. You can directly turn on / off, include items in general search, and change the action key
      • Improved support for additional window managers by abstracting out shell process calls
      • ~ will now act as the user home directory in Folder plugin
  • Bugfixes Highlights
    • Fix for PT Run registering the hotkey on non-supported OS versions (#9999)

v0.33 -> v0.35:

  • New Features & Improvements
    • Color Picker
      • Esc can now be used to exit the editor
    • FancyZones
      • Added hotkeys and quick swap functionality for custom layouts! Users can now assign a hotkey in the editor and use it to quickly set a desktop's zones with Ctrl + Win + Alt + NUMBER key binding, or by pressing the hotkey while dragging a window.
    • PowerToys Run
      • Users can specify where to show the launcher window
      • New plugin added to support opening previously used Visual Studio Code workspaces, remote machines (SSH or Codespaces), and containers! When enabled, use { to query for available workspaces. Please note, this plugin is off by default.
      • Shell history now saves the raw command instead of the resolved command. A command like %appdata% would now save in the Shell history as is instead of C:\Users\YourUserName\AppData\Roaming.
  • Bugfixes Highlights
    • PowerToys will start requiring Windows 10 v1903 or greater after 0.35.x release. (#9999)
    • Fixed FancyZones placement algorithm for when the Taskbar is vertical (#9999)

v0.29 -> v0.35:

  • New Features & Improvements
    • General
      • Added a 'First time load' experience. The hope is a quick, light way to learn about basic functionality
    • Color Picker
      • Esc can now be used to exit the editor
    • FancyZones
      • Dark mode for the editor
      • Certain settings (e.g. number of zones, spacing settings) can now be set on individual layouts.
      • New options to change zone activation algorithm
      • Added hotkeys and quick swap functionality for custom layouts! Users can now assign a hotkey in the editor and use it to quickly set a desktop's zones with Ctrl + Win + Alt + NUMBER key binding, or by pressing the hotkey while dragging a window.
    • PowerToys Run
      • Service management plugin (Start, stop, …)
      • Registry key plugin
      • System action plugin (Reboot, lock, ...)
      • Plugin Manager now is in settings. You can directly turn on / off, include items in general search, and change the action key
      • Improved support for additional window managers by abstracting out shell process calls
      • ~ will now act as the user home directory in Folder plugin
      • Users can specify where to show the launcher window
      • New plugin added to support opening previously used Visual Studio Code workspaces, remote machines (SSH or Codespaces), and containers! When enabled, use { to query for available workspaces. Please note, this plugin is off by default.
      • Shell history now saves the raw command instead of the resolved command. A command like %appdata% would now save in the Shell history as is instead of C:\Users\YourUserName\AppData\Roaming.
  • Bugfixes Highlights
    • Fixed OneDrive SVG Bug (#9999)
    • SVG are scaled appropriately when view box is provided (#9999)
    • Fix for PT Run registering the hotkey on non-supported OS versions (#9999)
    • PowerToys will start requiring Windows 10 v1903 or greater after 0.35.x release (#9999)
    • Fixed FancyZones placement algorithm for when the Taskbar is vertical (#9999)