Creator: Doc team

Audience: Course teams, Open edX community

Purpose: Communicate upcoming features to people who will be using them

Published: Partner and Open edX portals

Overview

The product update is a monthly newsletter for course teams and Open edX communities. The update focuses on upcoming features. It also describes recently released features, a spotlight feature (one that edX wants more course authors to use), and optionally best practices.

Format

Two versions of the product update are published each month.

• Partner: Published on the Partner Portal.
• Open edX: Published on the Open edX Portal.

The product update has the following sections as of May 2018. Format section headings as h2, not h1.

• Coming Soon for Learners
• Coming Soon for Course Teams
• Coming Soon for Open edX System Administrators and Developers (rare; in the Open edX version only—for features that would be documented in the ICR or developer guides)
• Coming Soon for Researchers (rare; includes information about Insights and the event logs, for both course teams and data czars)
• Coming Soon in Accessibility (rare—however, although these usually fit into one of the other categories, we call out a11y features and changes specifically because of the DOJ decree)
• Recently Released for Learners
• Recently Released for Course Teams
• Recently Released for Open edX System Administrators and Developers (rare; in the Open edX version only—for features that would be documented in the ICR or developer guides)
• Recently Released for Researchers (rare; includes information about Insights and the event logs, for both course teams and data czars)
• Recently Released in Accessibility (rare—however, although these usually fit into one of the other categories, we call out a11y features and changes specifically because of the DOJ decree)
• Feature Spotlight: Name of Feature
• Best Practices: Name of Best Practice

Under each heading, include an h3 for each paragraph or feature. Note that a feature can include more than one paragraph, or a paragraph can include more than one feature. Use your best judgment or consult with the doc team, product team, or product advocates for headings and the amount to say about each feature.

Note that the Open edX sections are only included in the Open edX version of the update.

Obtaining Content

Most content for the product update originates with the monthly B2C Roadmap Update presentations. The author might also include notes or other information as comments on the doc ticket for the specific monthly update (for example, see DOC-3911 - Getting issue details... STATUS ).

Usually, after the monthly B2C Roadmap Update meeting, the product update author meets with the product advocate team to decide which features to include and emphasize. 

Around the 23rd of the month, the author compiles a list of possible items and e-mails the list to the Product Org <product-org@edx.org> and Product Advocates <product-advocates@edx.org> distribution lists, asking for feedback. This e-mail generally also includes any other necessary clarifying questions.

The e-mail has the following subject line.

Please respond by <time> <day>, <date>: <month> product update content

The product team has the final say on which features the product update covers. 

Both the product team and the product advocates can help the author decide what, and how much, to say about each feature.

Writing the Draft

The product update is published on the portal. However, the author creates a draft as a Google doc for feedback purposes.

• Drafts are in the Product Updates folder.
• Drafts include all content for both the partner version and the Open edX version, indicated with highlighting.
• Drafts include live links.
• Drafts include images, placed approximately where they'll appear in the published update. For important information about images, see Adding Images.

Collecting Feedback

When a draft is ready, the author sends the following message to the Product Org <product-org@edx.org> and Product Advocates <product-advocates@edx.org> distribution lists.

Subject line: Please respond by <time> <day>, <date>: <month> product update

Setting Up the Update on the Portal

1. On the partner (not Open edX) portal, open the previous month's product update.
2. Between the title and the first line of text, select Clone content.
3. In the Title field, replace Clone of <former month> <year> Product Update with <current month> <year> Product Update.
4. Scroll to Domain Access Options.
5. Under Publish to, select edX Partner Portal. (Do not select Open edX Portal | Open Source MOOC Platform.)
6. Scroll to the panel at the bottom that has Revision information, URL path settings, and other tabs.
7. On the Publishing Options tab, select Draft.
8. Select Save.
9. Make a note of the URL. Otherwise, you might not be able to find the draft update again.*

      *Note: The product update URL almost always follows this pattern.

https://partners.edx.org/announcements/june-2018-product-update

The URL is the same whether the update is in draft or published form. However, if for any reason the URL does not conform to this pattern, you'll need to have the URL that you made a note of in step 9 to find your draft. You cannot search for the update on the portal until the update is published. 

Transferring the Text to the Portal

1. Go to the URL that you noted in step 9 of Setting Up the Update on the Portal, and then select Edit.
2. In the Text box, delete the existing images.
   Note Do not delete the Technical Support section or image at the end of the page.
3. Replace the existing text with the text from the Google doc.
4. Paste the text from the Google doc into a plain text editor, and then re-copy the text from the plain text editor and paste the text into the portal.
5. Add any headings or text formatting, such as numbered or bulleted lists and bold or italic text.
6. Use the link icon in the toolbar to add links.
   Note Make sure to select the Target tab and then select New Window (_blank) to make each link open in a new window.

Adding Images

For the Google doc, you don't have to worry about image size; make sure the image has a dark gray border and you can size it as you want to.

For the portal:

• Make sure every image has a 2-pixel wide, dark gray (Hex #414141 or RGB 65, 65, 65) border.
• Make sure the image files are no wider than 500 px. Even if you set a larger image file to be 500 px wide in the portal, the image will be the original size in the email version (which is what most people see).
  • To resize images, if possible use Photoshop, not SnagIt. Images become blurry when you resize them using SnagIt.
  • When you resize an image in Photoshop, in the Image Size dialog box, make sure that Resample is set to Bicubic Sharper (reduction).
• You can't see images in context in edit mode. You have to select Save at the bottom of the screen to view the image in context.

To insert an image:

1. Place the cursor where you want to add the image. This is usually immediately to the right of the last character of a heading.
2. In the toolbar, select the image icon.
3. In the Image Properties dialog box, select Browse Server.
4. In the (gigantic) screen that appears, select Upload in the menu bar, and then select Choose File.
5. In the dialog box that opens, locate and select the file on your computer, and then select Open.
6. Select Upload.
7. When the image has uploaded, it is automatically selected in the list of files. In the menu bar, select Insert File.
8. Specify settings for the image.
   1. Enter alt text for the image.
   2. In the HSpace field, enter 10.
   3. For the Alignment option, select Right.
   4. In the VSpace field, enter 10 if images are touching in the previewed output. 
9. In the Image Properties dialog box, select OK.
10. Select Save to close the editor and view the image in context.

Separating the Versions

After all final edits are complete, separate the product update into partner and Open edX versions.

1. On the Partner Portal, go to the URL for the product update that you've been working on, and then select Clone content.
2. In the Title field, replace Clone of <month> <year> Product Update with <month> <year> Open edX Product Update (note the "Open edX" in the title).
3. Scroll to Domain Access Options.
4. Under Publish to, select Open edX Portal | Open Source MOOC Platform.
5. Scroll to the panel at the bottom that has Revision information, URL path settings, and other tabs.
6. On the Publishing Options tab, select Draft.
7. Select Save.
8. Make a note of the URL. The URL at this stage conforms to the following pattern.
   https://partners.edx.org/announcements/june-2018-open-edx-product-update (note that it is on the partner portal, but has "open-edx" in the URL)
   
9. Go to the two URLs that you noted to open the drafts of both updates, and then select Edit. For example, for June 2018, you would go to both the following URLs.
   https://partners.edx.org/announcements/june-2018-product-update
   https://partners.edx.org/announcements/june-2018-open-edx-product-update
   
10. In the update for the partner portal (which does not have "Open edX" in the title or URL), delete all Open edX-only information.
    1. If any, ensure that you delete the (Partner only) placeholder text in h3 headings.
    2. If any, ensure that you delete the (Open edX only) placeholder text in h3 headings.
11. In the update for the partner portal, select all applicable options in the Audience and edX Product Area lists, and then select Save.
12. Repeat steps 10 and 11 for the Open edX product update.

Publishing the Product Updates

1. Open the drafts of both updates. 
2. Select Edit.
3. Scroll to the panel at the bottom that has Revision information, URL path settings, and other tabs.
4. On the Publishing options tab, clear the Draft option, and then select the following options.
   • Published
   • Promoted to front page
   • Send subscriptions notifications
5. (optional) To change the author or date of the announcement (for example, if you create a draft on the portal on April 28 but you want the publish date to be May 1), select the Author Information tab in the panel at the bottom of the page, and then make any changes you want.
6. Select Save.
7. View the product updates to make sure they appear as you want.
   Note When you select Save to publish the Open edX product update, the OE update becomes available on the Open edX portal. The URL that you used to edit the draft, which is a partners.edx.org URL, no longer works. To view the Open edX product update, go to open.edx.org, select Announcements, and look for the update that you just published.

Notifying Ed Services

After you publish both versions of the product update, send the following e-mail to Ed Services, changing the month and year as necessary.

To: Partner Management <partner-management@edx.org>,
ES Project Coordinators <es-service-coordinators@edx.org>

Subject: The April 2018 product update is live

Body:

Hi PMs and PCs,