...
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 would be 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 labels to each article (Outdated, Current, Misleading, etc)
- Use Confluence labels/Jira tickets to internally earmark documents for future review/edits
...
- 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 guidelines
- 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
...
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, hold establish a recurring Synapse docs meeting (or merge with existing Community docs meeting) to provide updates and facilitate discussion/participation in future doc initiatives.
...
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 a 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.
...