View source for Websites/Snippets/Rewrite

{{LastUpdated}}
{{TOC_limit|3}}

The Snippets Service Rewrite project is an attempt to rewrite the snippets service from the ground up using [https://github.com/mozilla/playdoh Playdoh] and other modern libraries that we use in current Mozilla sites. We also want to take advantage of the opportunity to redesign the mechanics of how the service works in order to make it easier to create new snippets and manage existing snippets, given how important the service is to our engagement efforts.

== Justification ==
Snippets is one of our largest channels for communicating with users. Snippets gets over 4 billion impressions a month, and we get a ton of requests for new snippets all the time. There hasn't been a lot of technical attention paid to the Snippets service for at least the past two years, and as a result the codebase has become stale. In addition, the administrative UI is not easy to use, and things like localizing snippets or putting out interactive snippets are unnecessarily hard. A few small tools and scripts have been made to help deal with these limitations, but we've hit the point that rewriting the service from the ground up makes sense.

The improvements we can add during the rewrite will make us more efficient in creating and managing snippets, and free up developer time to work on more engaging and interactive snippets. It will also help us put more snippets out to non-en-US locales by improving the localization process for snippets. We will also add features to reduce the chance of putting out invalid snippets that break about:home, which the current system doesn't have.

== General Goals ==
* Rewrite the snippet service using Playdoh.
* Update the hardware and deployment process for the Snippets service to use Chief and Commander for rapid deployment.
* Improve the ability for administrators to view and manage which snippets are live.
** Reduce complexity from current Client Match Rule system.
* Reduce the need for developer intervention when creating complex snippets or localized snippets.
* Reduce the chance of errors that break about:home (invalid XML, for example) that happen from time to time due to human error.

== Specific Improvements ==
* Add concept of snippet templates: Instead of each individual snippet having unique code, allow templates to be created that multiple snippets can use, such as a Video Snippet template.
** Templates will have placeholders for variables that admins fill in with information specific to that snippet, such as the URL for a video or a specific string.
* Add support for localization through the service, instead of by making multiple copies of the same snippet.
* Provide a mock about:home page for previewing what a snippet will look like, even a non-simple snippet.
* Move common Client Match Rules into default options (checkboxes or option buttons) for snippets. Client Match Rules should be only for special cases.
* Run XML validation and escaping on all snippets to avoid issues with invalid XML breaking about:home.
* Provide a good way for non-admins to see what snippets are currently active.

== Project Management ==

* tracking bug: https://bugzilla.mozilla.org/show_bug.cgi?id=866963
* kanban board: https://mozilla.kanbanery.com/projects/35613/board/

=== Timeline ===
http://publish.smartsheet.com/6d80ffeae4be4a849b6f66c30fd1e178

= L10n App =
One of the major components of the rewrite will be a user-facing localization app. Users will be able to log in and suggest translations, and certain users will have permission to log in to a special admin interface that lets them see suggested translations and choose which one is best, or add their own instead.

== Users ==
* '''Admin''' - Creates snippets via the admin interface.
* '''Approved Localizer''' - Controls which string is chosen as the accepted translation. 
* '''Community Localizer''' - Can suggest possible translations for a string.
* '''QA''' - Can double-check and make/suggest corrections to an accepted translation (only a few large locales have this).

== Stories ==
* As an '''Admin''', I can:
** See how many locales have completed translating a snippet.
** Mark a snippet as not available for localization.
* As an '''Approved Localizer''', I can:
** See a list of strings to translate and can filter it by locale and whether it has an accepted translation.
** See a list of suggestions for an individual string and can choose one as the accepted translation, or fill in my own string.
** Preview what a snippet would look like with a certain string.
** Save an approved translation for use in multiple locales (single translation for all es-* locales, for example).
* As a '''Community Localizer''', I can:
** See a list of strings to translate and can filter it by locale and whether it has an accepted translation.
** Suggest a translation for a string and see what my previous suggestion was.
** Preview what a snippet would look like with a certain string.
** Receive notifications when new strings are available for translation.
** Access some sort've data about snippets via JSON.
** View the translation interface in another language besides English.
* As a '''QA''', I can:
** Review the accepted translation for a string and make a correction (suggest a correction?)
** Preview what a snippet would look like with a certain string.

== Open Questions ==
* Do L10n QAs need anything more than a read-only view of accepted translations? Could we have them use the public interface for localizers and just offer useful filters?
* When should a string be put out for translation?
** Suggestion: If the snippet is enabled, the strings are available for translation unless it is past the published_end date.
*** Most snippets that don't have a published_end date are long-term snippets that don't need an end date, thus there shouldn't be many strings that are up for translations but not used.
* Do admins need the ability to select priority locales?
** How would localizers be notified that certain snippets are a high-priority?
** Suggestion: Leave this for a later iteration. 
* Is the need for a JSON API just for seeing what strings are available for translation, or do we want more, like a way to pull the translations out of the system via the API?

== Pages ==
=== Public Community Localizer Interface ===
* Global Header
** Has Persona login/logout button
* List of strings to translate
** Auto-choose locale, allow to switch to another locale, save in a cookie for next time.
** Filter list by translation status (untranslated, user has suggested a translation, string has approved translation)
* Suggestion detail page
** Show preview of snippet in an iframe with translations applied.
*** If snippet has strings without suggested translations, use the user's own suggestion for it, or English if none is found.
** Update preview as user enters in suggestion.

=== Admin Approved Localizer Interface ===
* Admin log in
** Auths user via LDAP? Or maybe Persona, and verify email ends in mozilla.com? Or maybe Persona/username and password, but an admin gives their account permission for translation?
* List of strings to translate
** Filter by locale, translation status.
* Translation detail page
** Show preview of snippet in iframe with accepted translation applied.
** Live update preview as accepted translation changes.
** Show list of suggestions from users.