Initial SCOOBE Spec added #10978
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||
|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,185 @@ | ||||||||
| # 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.](https://github.com/microsoft/PowerToys/issues/1285) | ||||||||
|
|
||||||||
| **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 | | ||||||||
|
There was a problem hiding this comment. This opens the door to inconsistencies between OOBE and SCOOBE. |
||||||||
| |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 | | ||||||||
|
There was a problem hiding this comment. This is also something that should be discussed because it makes the implementation and testing overwhelming for our team that is too small to keep adding features that provide little benefit to the users but are a potential source of bugs and add complexity to the development and testing phases. |
||||||||
| |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 | | ||||||||
|
There was a problem hiding this comment. This is another feature that will require a significant amount of testing and could be a potential source of bugs bringing very little benefit to the users and also limit those users that are regularly updating but might skip checking SCOOBE for some releases, but that would still like to reopen SCOOBE at a later time to check previous updates to see the new features. Showing a version-to-version list of updates would cover all the scenarios and not have any limitation in terms of information provided. |
||||||||
| |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 | | ||||||||
|
There was a problem hiding this comment. Given my previous comment this would become irrelevant. |
||||||||
| |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 | | ||||||||
|
|
||||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||||
| **\*** - 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. | ||||||||
|
There was a problem hiding this comment. Any plans to caching the data for the case that no network is available when the user reopens the oobe section? There was a problem hiding this comment. This point also applies to OOBE, but as explained in previous comment, it's important to keep them in sync. The ability to update just SCOOBE is bring little to no benefits to the users, but brings more complexity for development and testing and opens the door to inconsistencies with OOBE. |
||||||||
|
|
||||||||
| **\*\*** - 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)](https://github.com/microsoft/PowerToys/releases)). | P1 | | ||||||||
|
|
||||||||
| **3.2. Open Discussion** | ||||||||
|
|
||||||||
| - How do we localize content like keystrokes and visuals? | ||||||||
|
There was a problem hiding this comment. I would localize keystrokes not until #9482 is implemented There was a problem hiding this comment. The problem is here is not just how to localize content like keystrokes, the problem is the added complexity to the entire localization process and the fact that SCOOBE needs to implement its own logic to determine what locale should be used, adding another layer of complexity for both development and testing. Specifications for the entire localization process and specification for how SCOOBE should programmatically manage localized resources must be fully specified. |
||||||||
|
|
||||||||
| - How do we make keystrokes/activation phrases stand out? | ||||||||
|
There was a problem hiding this comment. |
||||||||
|
|
||||||||
| - 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? | ||||||||
|
There was a problem hiding this comment. This is a show stopped and unless there is a full specification, it is pointless to even consider starting the SCOOBE development. |
||||||||
|
|
||||||||
| - Should we store SCOOBE information for all versions of PowerToys? If not, how far back should we maintain information? | ||||||||
|
There was a problem hiding this comment. Do we have telemetry data on how many users are using version ... . If so we should look at that for this decision There was a problem hiding this comment. More interesting here are the telemetry data of update path like from 0.33 directly to 0.37. |
||||||||
|
|
||||||||
| ## 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 | | ||||||||
|
There was a problem hiding this comment. Not sure what are the implication of this requirement. |
||||||||
| |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 | | ||||||||
|
There was a problem hiding this comment. This is also very unclear. If SCOOBE is shown when the new version is executed for the first time, how could this result in a value that is not 100%? |
||||||||
| |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 | | ||||||||
|
There was a problem hiding this comment. It is unclear what this is, since the content is dynamic, how would SCOOBE detect that the user has clicked on link to the settings page for a particular module? |
||||||||
| |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 | | ||||||||
|
There was a problem hiding this comment. Same as for the previous point. This needs a full specification. |
||||||||
| |6. | Screen size | Gives crucial information for considerations related to minimal/maximum window size needed for displaying content. | P2 | | ||||||||
|
There was a problem hiding this comment. This screen size information is already available as part of the system telemetry. |
||||||||
|
|
||||||||
| ## 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) | ||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think that can be achieved by adding images of the new features and links like "try it out"