...

Project Overview 

We are standardizing the processes and tools that we use to manage user documentation so that critical information is easier to find and share (see User Support Assessment). We selected Confluence as the primary authoring and publishing platform at Sage for its accessibility and centralization. Moving to the Confluence platform will allow us to improve our internal workflows for managing documentation, as well as improving navigation, search, and information taxonomy for external users on the Synapse help site (see Authoring Tool Proposal). This document describes the work plan for achieving those goals. 

...

The following task list divides the work into phases, roughly in chronological order. Stacey will lead on all activities except where indicated.  The estimated timeline for this migration is here, and the anticipated launch date for the new Synapse doc site is mid-May 2021.

•  Evaluate existing content on docs.synapse.com(March)
•  Outline all existing sections and subsections, evaluate information taxonomy
•  If changes are necessary, perform a card sort and propose structural changes for Design and other stakeholders to review
•  Evaluate existing article quality to triage/prioritize articles for future improvements, assign create Jira tickets to internally earmark documents for future review/edits. Assign labels to each article ticket for tracking (Outdated, Current, Misleading, etc)  
Use Confluence labels/Jira tickets to internally earmark documents for future review/edits

•  Tool configuration (backend) (March)
•  Set up Confluence spaces (page structure, global permissions, space settings)
•  Configure Comala Document Management workflows for editorial review/approval
•  Configure Comala Publishing to sync between Draft and Published spaces
•  Configure custom domain (led by Engineering)
•  Map redirects for existing URLs (Stacey maps, Engineering implements)

•  Site configuration (front end) (March)
•  Choose 1 favicon, 1 banner image, and color scheme to coordinate with Synapse Homepage (led by Design team -- these graphics can be reused from the existing Synapse homepage)
•  Configure site layout and components in Viewport dashboard
•  Design review and input on custom CSS options

•  Migrate and Review (April)
•  Transfer all existing articles, images, and associated files from GitHub to Confluence
•  Copy edit articles for consistent grammar, spelling, formatting, broken links, and any artifacts from GH/Jekyll
•  Ensure articles adhere to style/formatting guidelines
•  Resize images where needed
•  Stage the new site and invite stakeholders to review for issues/bugs

...

•  Set up process workflows (late April/early May)
•  In Confluence, define contribution workflows and write SOPs for contributors, beta test SOPs with a pilot group (ideally 1-2 reps each from Governance, Engineering, Design, Research)
•  Copy style guide from GitHub README to Confluence, add guidelines for article types/templates
•  Set up Jira project for Synapse docs, decide on stages/labels/required fields
•  Sync existing GH issues to a Jira backlog 
•  Establish Confluence page templates for new docs (e.g. concept, procedure, reference, troubleshooting)
•  Create a process for external users to file new issues in Jira queue -- either GH issues linked to Jira for now (workaround) or Jira Service Management or similar

•  Pre-launch (early May)
•  Announcement to internal/external stakeholders (collaborate with Hsiao-Ching, see below)
•  Demo for internal stakeholders

•  Launch (mid-May)
•  Site goes live
•  Training for doc contributors begins (see below)

...

Communication with all stakeholders, both internal and external, will be critical for a successful migration and site launch. Externally, pre-launch announcements will help to set expectations for how and when the Synapse support experience will be changing. Internally, regular updates on project milestones will increase project visibility across the organization and encourage greater participation in the documentation process. 

External user community (in collaboration with Hsiao-Ching):

• Notify all Synapse users that the doc site will be changing: 

  • One email sent 3-4 weeks prior to launch notifying users of launch date and what to expect, cross-posted in Synapse help forum.

  • One email sent at launch to announce the new site, also cross-posted in Synapse Help Forum.

  • Potential for Twitter announcement(s) in-tandem with above.

• Banner or other notification on docs.synapse.com to announce the upcoming changes for all site visitors (will need Web Engineering to advise/facilitate).
  

Internal stakeholders and Sage users:

• Publicize this migration plan: link to this doc in Sage newsletter, Synapse report, and Synapse Slack channels (#synapse_docs and #synapse).

• Post progress updates in monthly Synapse report and on Slack.  The target frequency for updates will be one every 2-3 weeks until launch.

• Demo the site for all internal staff immediately before or after launch, likely at an All Staff demo day.

• If enough interest, establish a recurring Synapse docs meeting (or merge with existing Community docs meeting) to provide updates and facilitate discussion/participation in future doc initiatives. 
  

...