Skip to end of banner
Go to start of banner

Synapse Doc Migration Plan

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 39 Next »

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. 

Project Scope

The purpose of this project is to migrate the existing content on docs.synapse.org from GitHub to Confluence, then configure and launch a new Synapse documentation website. Additional work phases to improve and add content to the site will be addressed after migration and launch are complete. 

Project Outcomes 

  • Improve information architecture, navigation, search, and design of the existing docs.synapse.com help site

  • Make basic improvements in overall consistency, style, and formatting for all articles

  • Evaluate existing support content and prioritize articles for future revisions

  • Establish workflows for contributing, editing, and publishing docs on the Confluence platform

  • Enable all Sage staff to participate in creating or improving user documentation

  • Increase awareness of advanced Confluence features that facilitate more efficient knowledge management

  • Enable wider adoption of the Confluence platform for internal documentation needs.

Work Phases

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, create Jira tickets to internally earmark documents for future review/edits. Assign labels to each ticket for tracking (Outdated, Current, Misleading, etc) 

  • 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 Strategy

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. 

Training Plan

The success of a new tool and its associated workflows depends on widespread user adoption. To facilitate quick onboarding, doc contributors will be trained on the new workflows for creating, editing, and reviewing documentation. Additionally, we will also develop training on best practices for general knowledge management within Confluence. Together, these training resources will encourage more deliberate and consistent use of Confluence for a variety of documentation and support needs, centralizing information and making it easier to find. 

  • SOPs describing how to file a doc issue, how to propose a new article, and how to edit/review in Confluence. These SOPs will be tested with a small group of pilot users before roll out for all contributors.

  • Live training to walk through the new workflow for doc stakeholders -- recorded and archived so it can be referenced later (e.g. new employee onboarding). This training could be delivered at an All-Hands meeting, or it could be targeted to smaller groups of stakeholders for more Q&A.

  • A workshop on best practices for knowledge management using Confluence, initially for the monthly PM group meeting.  The goal of this session will be to demonstrate key features and strategies for organizing and maintaining internal documentation in Confluence, essentially developing more Confluence power users. If there is interest, this session could also be delivered to additional groups or to all staff.

Dependencies and Risks

There are a number of risks associated with conducting a successful doc migration. 

  • Schedule slip (high risk) 

    • Description: Stacey’s highest priority will be this migration project, however she will be balancing this work with other responsibilities (e.g. community doc development, community help site configuration and launch, evaluating support ticketing systems, etc). Work on Synapse doc migration will be interleaved with all of these responsibilities and consequently the timelines will need to be flexible. Additionally, it is likely that we will encounter minor unforeseen issues during migration that will require additional work time or course corrections. 

    • Mitigation: The project schedule has been planned with 1 extra week of reserve time to account for the unexpected. 

  • Tools experience (medium risk)

    • Description: Although we vetted each tool carefully during our evaluation phase, we may uncover unexpected issues with our chosen toolset as we get further into implementation. While we do not expect these to be major blockers, we may need to develop workarounds to keep the project on track.

    • Mitigation: The Comala and K15t support teams have been highly responsive during our tool evaluation. K15t in particular has been extremely quick to respond to bugs/suggestions for feature improvements. If technical issues arise, we will continue to work with these teams to design a workaround.

  • Internal adoption (low risk) 

    • Description: As with any new tool, it is possible that internal stakeholders will not initially see the benefits of migrating to Confluence and will resist adoption. Fewer participants in the documentation process will lead to continued fragmentation of our user docs. 

    • Mitigation: We will offer a variety of training options to increase awareness of and familiarity with using Confluence workflows. These training sessions will highlight how the new system benefits all users and will make our doc process more efficient and increase overall doc quality. 

Post-Launch Activities 

  1. Archive synapseDocs GitHub repository.

  2. Develop a plan for edits/re-writes to improve existing Synapse articles: who will contribute, how to identify and prioritize improvement areas, when to schedule work phases. The initial focus will be on improving/updating content for onboarding articles, as well as creating more consistency in structure/templating throughout the docs. Ideally, this work will coincide with setting mid-year objectives. 

  3. Develop a user survey to assess documentation needs and post it on the Synapse help site to gather feedback regularly.

  4. Develop a roadmap for programmatic doc improvements: who will contribute, what needs improvement, when the work will occur. Explore tools to integrate auto-generated content from Python, R, and CLI websites into Confluence for a unified user doc site through Viewport. Create additional onboarding vignettes and How-To articles for programmatic users; explore a Jupyter notebook integration with How-To articles. 

  5. Create content strategy for video vignettes and create 3-5 core videos demonstrating key features. The initial focus will be onboarding topics that have a relatively stable shelf life.

  • No labels