Revision as of 23:52, May 19, 2020 by Tanyai (talk | contribs)
Jump to: navigation, search

Deprecations in Genesys Engage cloud

UNDER DEVELOPMENT

This article describes the process to follow when a feature, service, capability, or application is put on the deprecation track, so that it eventually becomes unavailable to Genesys Engage cloud (former PureEngage Cloud or PEC) customers.

Deprecations at a glance

The Deprecations process applies to the features, services, capabilities, or applications that Product Management decides to remove from the Genesys Engage cloud environment. Essentially, the Deprecations process is analogous to the processes that Genesys Engage follows for on-premises products: Discontinuation of Support (for features, capabilities, or 3rd party components) or End of Life (for services or products). In many cases, a replacement feature, service, capability, or application is offered to customers as part of the Deprecations process. (For simplicity, the terms feature deprecation or deprecation are used in this article to mean any feature, service, capability, or applications that falls under the Deprecations process.)

A given feature deprecation must be approved by Product Management and PM Operations and must be communicated internally before the deprecation announcement is published for customers on the documentation site. The Technical Writer for the relevant product/functional area is responsible for creating a customer-facing deprecation article and Release Note and publishing them on the announcement date. When the feature finally reaches the deprecation date, the Technical Writer publishes a subsequent update to the deprecation article and Release Note. A time window (usually, six months) between the announcement date and deprecation date allows Genesys Engage cloud customers to prepare for the change in their environment.

The complete process is outlined on the Release Management site:

https://genesyslab.sharepoint.com/sites/releasemgmt/SitePages/EOL-Preparation.aspx

In particular, refer to the slide deck named Genesys Engage Cloud Feature Deprecations (by Product Management Operations), at the bottom of the referenced page.

JIRA Tracking

To keep track of the milestones and tasks associated with deprecations, the JIRA ticket template captures the workflow and responsibilities of different members of a product team:

The Product Manager who initiates the deprecation process uses the JIRA template to create a ticket and subtasks specific to a particular feature deprecation. While subtasks 1 and 2 are completed prior to and on the announcement date, the remaining subtasks are performed closer to and on the deprecation date. Because of the time gap of up to six months between these two dates, it is a good practice to keep any essential records and comments in the main ticket rather than in the subtasks.

Subtask 1. Documentation Inputs: Product Management inputs for the Deprecation article on the Genesys Engage documentation site

This task is for the Product Manager to provide documentation inputs for Deprecation article and Release Notes, in the main Deprecation ticket for <FEATURE/SERVICE NAME>.

Subtask 2. Deprecation article and Release Notes publication

  1. The Technical Writer prepares a Deprecation article and Release Note entry based on the inputs in the main Deprecation ticket for <FEATURE/SERVICE NAME>.
  2. The Technical Writer publishes the Deprecation article and Release Notes on the Announcement date.

If a separate ticket is necessary to track updates to product documentation, other than the Deprecation article and Release Notes, the Technical Writer uses the Add Documentation button in the main Deprecation ticket. This creates a Documentation task to track the work required to remove feature description and references.

Subtask 3. Technical clearance: This task is for Development and/or QA to verify that <FEATURE/SERVICE NAME> has been removed/disabled.

Subtask 4. Actual deprecation date confirmation: This task is for the Product Manager to confirm the actual deprecation date for: <FEATURE/SERVICE NAME>.

The Product Manager must provide any updates regarding the date and final wording for the Deprecation article and Release Note, in the main Deprecation ticket for <FEATURE/SERVICE NAME>.

Subtask 5. Final publications:

  1. The Technical Writer is to update the Deprecation article and create a new Release Note entry in preparation for the final Deprecation date for <FEATURE/SERVICE NAME>.
  2. The Technical Writer is to re-publish the Deprecation article and publish the new Release Note entry on the final Deprecation date.

Instructions for Technical Writer

A deprecation article and Release Note are the two deliverables that are required for a deprecated item, at a minimum. The Product Manager provides inputs for these two deliverables in the Deprecation JIRA ticket. The Technical Writer must ensure that resulting article and Release Note entry comply with Cloud style, in particular in the use of imperative and active voice, and adhere to the rules of English grammar, spelling, and punctuation. In the majority of cases, updates to existing articles and documents for the related features, products, or functional areas are also necessary. It is responsibility of the Technical Writer to assess the documentation needs and any cross-product dependencies around the announcement date and to complete documentation updates or article removal by the deprecation date. The Add Documentation button on the main Deprecation JIRA ticket can facilitate creation of a JIRA ticket to track additional documentation updates.

Things to do

Before the Deprecation announcement date:

  1. Create a Deprecation article (see how)
  2. Create a Deprecations portal page for product/functional area, if one does not exist (see how)
  3. Prepare Release Note for the announcement date (see how)

On the Deprecation announcement date:

  1. Publish the Deprecation article (see how)
  2. Publish the Product-specific Deprecations portal page, if not published yet (contact the Doc Platform team for assistance)
  3. Publish Release Note (see how)
  4. (Optional) Tag existing feature documentation as To Be Deprecated

Before the final Deprecation date:

  1. Update the Deprecation article (see how)
  2. Prepare Release Note for the final deprecation date (see how)

On the final Deprecation date:

  1. Re-publish the Deprecation article (see how)
  2. Publish Release Note (see how)
  3. (Optional) Remove documentation for the deprecated feature

How to create a Deprecation article

The Deprecation article template simplifies creation of a new article. After you receive, through the Deprecation JIRA ticket, complete inputs about the planned deprecation from the Product Manager, create the Deprecation article:

  1. Navigate to the Workspace Administration Dashboard for the respective product or functional area.
  2. On the Workspace Administration Dashboard, find the Manage Standalone articles section.
  3. Click Add a Deprecation Notice.
  4. Fill out the form:
    4a. Enter the official name of the feature (service, capability, or application) that will be deprecated.
    4b. Select PureEngage as the Platform.
    4c. In the column for Release Notes, add a link to the Release Note page for the respective product in the draft version of PEC Release Note:
    https://docs.genesys.com/Documentation/PSAAS/draft/RN/Welcome
    4d. Use Product Manager’s inputs from the Deprecation JIRA ticket to populate sections of the article:
    Announcement date: <Month DD, YEAR>
    Deprecation date: <Month DD, YEAR>
    Description: <Text of the deprecation description>
    Recommended Alternative: <Suggestion of new feature/functionality as successor, as applicable>
    Explanation: <Rationale for the deprecation or retirement appropriate for customer-facing document. Provides answers to potential customer questions:>
    • Am I affected?
    • How can I prepare for this deprecation?
    • What if I need help or have questions? (Any guidance aside from contacting MySupport.)
  5. After you save the draft article, go to the draft version of the System-level Deprecations portal for Genesys Engage cloud:
    https://all.docs.genesys.com/Draft:System/AllDeprecations
  6. Verify that the new deprecation item appears on the portal page with the correct name, dates, and links.
  7. Go to the draft version of the Product-specific Deprecations portal for the respective product/functional area and verify that the new deprecation item appears on the portal page with the correct name, dates, and links.

Note: If this is the first deprecation item within this particular product or functional area, you will need to create a Product-specific Deprecations portal page.

How to create a Deprecations portal page for product/functional area

For the first deprecation within a particular product or functional area, you must create a Deprecations portal page under the respective Workspace. This and subsequent deprecations for the same product or functional area will automatically appear on the portal page.

Example: https://all.docs.genesys.com/PEC-REP/AllDeprecations

To create a draft of the Product-specific Deprecations portal:

  1. On the Workspace Administration Dashboard, find the Manage Standalone articles section.
  2. Click Create Deprecation List page. This button is not displayed if the Deprecations portal page already exist, even as a draft.
  3. Follow the prompts.
  4. Select PureEngage as the Platform.
  5. On the draft portal page, verify the following:
    • The name and dates are correct for the new deprecation item.
    • The FAQ section is named “Genesys Engage Deprecations FAQs” (that is, specific to Genesys Engage as opposed to Genesys Cloud).

How to prepare Release Note for the announcement date

If the announcement date for a given deprecation item coincides with a Cloud release date for the respective product or service, add a section called Deprecations after the What’s New section in the Release Note entry for the release. In the Deprecations section, describe the future deprecation item using the Release Note input from the Deprecation JIRA ticket. Use the following syntax:

<FEATURE/SERVICE NAME> — On <Deprecation date entered as Month DD, YEAR>, Genesys will deprecate <FEATURE/SERVICE NAME>.
<Deprecation details, anywhere from one sentence to two paragraphs, ideally including reference to the replacement feature/service>. For more information, see <Link to the Deprecation article>.

If the announcement date falls outside of the product release cycle, add a new Release Note entry titled with the announcement date, without including the release number. The Deprecations section will be the only section in the Release Note entry (because the What’s New and Resolved Issues sections are not required).

Example

See the Genesys Interactive Insights (GI2) Deprecation announcement drafted in GCXI Release Note. 

==April 30, 2020==
===Deprecations===
*'''Genesys Interactive Insights''' — On November 20, 2020, Genesys will deprecate the legacy historical reporting product called Genesys Interactive Insights (GI2).
*:<br/>
*:Genesys Customer Experience Insights (Genesys CX Insights or GCXI) is offered in Genesys Engage cloud (formerly known as PureEngage Cloud) as the new historical reporting tool that replaces GI2. GCXI provides a presentation layer that extracts data from the Genesys Info Mart database and presents it in readable historical reports, thereby enabling business and contact center managers to make better business decisions for streamlining operations, reducing costs, and providing better services. For more information, see [https://all.docs.genesys.com/Draft:PEC-REP/Deprecation-Genesys_Interactive_Insights Deprecation: Genesys Interactive Insights].

How to publish a Deprecation article on the announcement date

Prior to publication:

  • The Product Manager, other members of PCT, and any members of the extended product team designated by the Product Manager must review and approve the article.
  • Another Technical Writer has to peer-edit the text of the article.

To publish a Deprecation article:

  1. Access the draft article.
  2. In the Edit mode, change the Release Note link to point to the product page in the Public version of PEC Release Note (rather than the draft version), and save the change:

https://docs.genesys.com/Documentation/PSAAS/latest/RN/Welcome

  1. Click Page actions and select Publish page.
  2. Wait until the public version of the page is created.
  3. Verify that the new deprecation item appears on the published System-level Deprecations portal page: https://all.docs.genesys.com/System/AllDeprecations
  4. Verify that the new deprecation item appears on the published Product-level Deprecations portal page for the respective Workspace.

Note: If this is the first deprecation within a given Workspace, the Product-specific Deprecations portal page for the product/functional area might not have been published yet. Contact the Doc Platform team for assistance with publishing the portal page.

How to publish Release Note on the announcement date

Prior to publication:

  • The Product Manager, other members of PCT, and any members of the extended product team designated by the Product Manager must review and approve the Release Note entry.
  • Another Technical Writer has to peer-edit the text of the Release Note entry.
  • Pubs Editors have to approve the Release Note format.

To publish the Release Note with the Deprecations section, use the regular process for publishing Release Notes for new releases to Genesys Engage cloud (former PEC).

How to update a previously published Deprecation article

Close to the final deprecation date, when the feature, service, capability, or application is confirmed to be ready for removal, update the draft version of the Deprecation article. At a minimum, change the verbs from future tense to past tense, where necessary. For instance, replace “will remove” or “will deprecate” with “removed” or “deprecated”. Additionally, consult the Product Manager regarding changes to any other statements, references, or timelines in the Deprecation article.

How to prepare Release Note for the final deprecation date

If the final deprecation date for a given deprecation item coincides with a cloud release date for the respective product or service, add a section called Deprecations after the What’s New section in the Release Note entry for the release. In the Deprecations section, describe the deprecation item using the updated Release Note input, if available, from the Deprecation JIRA ticket. Use the following syntax:

<FEATURE/SERVICE NAME> — On <Deprecation date entered as Month DD, YEAR>, Genesys deprecated <FEATURE/SERVICE NAME>. <Short statement with reference to the replacement feature/service, if available>. For more information, see <Link to the Deprecation article>.

If the announcement date falls outside of the product release cycle, add a new Release Note entry titled with the deprecation date, without including the release number. The Deprecations section will be the only section in the Release Note entry (because the What’s New and Resolved Issues sections are not required).

How to re-publish the Deprecation article on the final deprecation date

Prior to publication:

  • THe Product Manager, other members of PCT, and any members of the extended product team designated by the Product Manager must review and approve the updates to the article.
  • Another Technical Writer has to peer-edit the text of the article.

To re-publish the Deprecation article:

  1. Access the updated draft article.
  2. Click Page actions and select Publish page.
  3. Wait until the public version of the page is updated.
  4. Verify that the deprecation item appears correctly on the published System-level Deprecations portal page: https://all.docs.genesys.com/System/AllDeprecations
  5. Verify that the deprecation item appears correctly on the published Product-level Deprecations portal page for the respective Workspace.

How to publish Release Note on the final deprecation date

Prior to publication:

  • The Product Manager, other members of PCT, and any members of the extended product team designated by the Product Manager must review and approve the Release Note entry.
  • Another Technical Writer has to peer-edit the text of the Release Note entry.
  • Pubs Editors have to approve the Release Note format.

To publish the Release Note with the Deprecations section, use the regular process for publishing Release Notes for new releases to Genesys Engage cloud (former PEC).

Examples

PureEngage Cloud Release Notes, GI2 entry in GCXI Release Note for April 30, 2020: https://docs.genesys.com/Documentation/PSAAS/Public/RN/CXI

System-level Deprecations portal page: https://all.docs.genesys.com/System/AllDeprecations

Reporting Deprecations portal page: https://all.docs.genesys.com/PEC-REP/AllDeprecations

Genesys Interactive Insights Deprecation article: https://all.docs.genesys.com/PEC-REP/Deprecation-Genesys_Interactive_Insights

Comments or questions about this documentation? Contact us for support!