...
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) Create 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)
...