Cover suffix some more

client/state/themes/README.md

@@ -59,16 +59,18 @@ data: {
 }
 ```
 
-This means that individual theme information is stored in the `items` object, while the `queries` object associates serialized queries with the corresponding themes (stored per theme ID in `itemKeys`).
+This means that individual theme information (like theme name, description, screenshot link etc) is stored in the `items` object, while the `queries` object associates serialized queries with the corresponding themes (stored per theme ID in `itemKeys`).
 
 Jetpack Sites
 -------------
 
 Jetpack sites come with a REST API endpoint that triggers installation of a theme from either WordPress.org, or WordPress.com. To tell Jetpack which of either repository to use, we append a `-wpcom` suffix for WP.com themes. The suffix is then also present in the installed theme's ID (and directory name). There's another reason for that, which is to avoid collisions with existing themes in the WordPress.org repository -- otherwise, the WP.com theme would get overridden with a WP.org one of the same name by the self-hosted site's updater. Instead, downloaded WP.com themes include a little plugin that updates them from WP.com.
 
+To the user, we hide the `-wpcom` suffix as much as possible, e.g a selector like `getActiveTheme()` will remove it from its return value. The reason is that we want the UX to be as seamless as possible: When a user is looking at the Theme Details Sheet for a WP.com theme for their Jetpack site, i.e. wordpress.com/theme/ixiom/example.com and press the 'Activate' button, we need the UI to update accordingly, e.g. change the button from to 'Customize' after activation. Scenarios like this wouldn't be possible if we were exposing the suffix.
+
 ### Automated Transfer
 
-There's one exception to this, which is Automated Transfer (AT) sites. While handled through Jetpack, the `-wpcom` suffix is absent from installed themes there, mostly to facilitate transfer of theme options from WordPress.com. The WordPress core updater isn't of any concern there. Instead, AT itself manages WP.com themes to be always up-to-date.
+There's one exception to the `-wpcom` suffix, which is Automated Transfer (AT) sites. While handled through Jetpack, the `-wpcom` suffix is absent from installed themes there, mostly to facilitate transfer of theme options from WordPress.com. The WordPress core updater isn't of any concern there. Instead, AT itself manages WP.com themes to be always up-to-date.
 
 ### Filtering of WP.com Themes on Jetpack Sites