Synapse Doc Migration Plan
- Stacey Taylor (Unlicensed)
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.
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
Archive synapseDocs GitHub repository.
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.
Develop a user survey to assess documentation needs and post it on the Synapse help site to gather feedback regularly.
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.
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.