Overview
Synapse Docs Admin Workflow
File a Jira and triage- Anyone can file a Jira ticket in the Docs Project. New Jira tickets are automatically assigned an Open status, meaning that they have not been triaged yet. Issue reporters may wish to assign an issue directly to themselves if they want to own the edits, otherwise, you (the admin) triage the ticket by choosing an assignee and then filing the ticket into Backlog, Selected for Development, or In Progress. You also groom the backlog and manage all in progress work on the board, closing tickets when the work is complete.
Edit in Confluence - Once a ticket has been assigned to you or someone else, that person goes to the appropriate page in the Synapse Docs (Working Drafts) space and makes the requested changes. See the Contributor Guide for more information on how to contribute to the docs, particularly this section on how to save an edit with a version comment.
Request approval - Once an edit to a page is made and published to Confluence, whoever made the edit must initiate the approval process for that page. To initiate approval, click the Review button at the top of the Confluence page and assign an approver (see this section of the Contributor Guide for more detail). All approvals MUST include you (an admin) as one of the approvers. If needed, additional subject matter experts can also be added to approve the doc.
Approval/Rejection - As an admin, you must review the page edits for the following:
Adherence to the Style Guide.
If new links to other Synapse Docs articles were added, you must either use the external-facing Viewport link (e.g. help.synapse.org/docs/articlename) OR use the URL to the corresponding Confluence page in the final draft space, not the working draft space.
If new images were added, check the Viewport preview to make sure they are sized appropriately.
Sync approved page to final draft space - Once you approve the page, you must sync it to the final draft space so that Viewport can pick it up in the next build. To sync a page, click the Out of Sync button at the top of the page (
) and then Publish. You should see a notification that Comala Publishing has successfully synced this page with the final draft space. If you get an error, reload the page and try again. Update Viewport site - As an admin, you are responsible for pushing updates from the final draft space to the Viewport site. Currently, there is no fixed schedule for pushing updates, and new edits are pushed ad hoc. In the future, weekly pushes may be more convenient. Detailed instructions with screenshots for how to update a Viewport site can be found here.
Synapse Doc Toolchain
This section describes each tool in the Synapse doc toolchain, what it is used for, how it is set up, and options for configuring the tool further. To read more about the initial doc tool requirements and vetting process, see the Authoring Tool Proposal and the Doc Tool Evaluation Matrix.
Jira
The Docs Project on Jira is the main tool for tracking Synapse doc issues, tasks, and work in progress. Any work on Synapse docs must be recorded in a Jira ticket on this board so that we have one place to collect issues and see all upcoming/current work.
Setup
Briefly describe setup
Confluence
Confluence is the main authoring and editing tool for user docs at Sage, and it was chosen because of its accessibility for non-technical doc contributors as well as its ability to centralize docs across all of Sage.
Setup
For Synapse Docs, there are two main Confluence spaces that are used to manage content. The first space, Synapse Docs (Working Drafts), is where all edits, reviews, and approvals take place. This space is visible to all Sage employees, and anyone can edit the docs, comment, or review changes. Think of this space as a staging area.
The second space, Synapse Docs, is a space for final drafts only and is what drives the http://help.synapse.org doc site. This of this space as the production site. Finalized, approved pages from the working draft space are copied to the final draft space where they are published with the Viewport app. This separation is necessary because it creates one space where anyone can work “behind the scenes” on asynchronous edits to any page without these changes going live accidentally. The final draft space is only visible to Synapse Doc admins and should NOT be made public to the rest of Sage to avoid someone accidentally making edits directly to this content.
Comala Doc Management (Confluence App)
Comala Doc Management is a Confluence App that is used for doc control within the Synapse Docs (Working Draft) space. This app adds the ability to assign reviewers to a page in Confluence, and then track the review and approval process in a central dashboard. You can also configure custom review/approval workflows for any Confluence space. An approval process is necessary so that any new content or edits to the Synapse Docs site are gated and require an admin review before those changes appear on the live Synapse Docs site, thus ensuring quality control. Without this app, Confluence does not have a mechanism to manage and track a review and approval process. Comala Doc Management adds a button to initiate an approval at the top of every doc, and it also creates a Workflow Report dashboard where administrators can see the review/approval status of every document in a Confluence space.
Setup
Currently, Comala Doc Management is configured for the Synapse Docs (Working Drafts) space with a default approval workflow. There are three states that a Confluence page can be in: Review, Approved, and Rejected. The Review state is the default; whenever a Confluence page is changed, this status indicates that it is under review and/or edited. Pages in this state can be assigned to specific reviewers, and once those reviewers approve the document, it transitions to the Approved state. If rejected, the page transitions to the Rejected state.
Any updates/edits to a page in the Approved or Rejected state will automatically transition the page back to the Review state. Any comments to a page will not change the state. For example, comments about a typo on an approved page will not change the status, however edits to fix that typo will push the page back to a Review state.
Note that you can completely customize the approval workflow to add statuses or different transition paths between statuses. You can also customize different approval workflows for other Confluence spaces and re-use workflows from space to space. Additionally, you can customize the messages that reviewers see when they are notified. See the Comala Doc Management Cloud User Docs for instructions on how to further customize the app.
Comala Publishing (Confluence App)
Comala Publishing syncs Confluence pages from one space to another, essentially making an exact copy of one page in another space and then updating that copy each time the page is re-synced. This functionality is critical to the Synapse docs workflow because it allows us to separate working drafts from final drafts so that only final drafts appear on the Synapse Docs website. Essentially, this app enables Confluence content to be selectively pushed to the production site.
Setup
This app is relatively straightforward to configure and setup involves selecting a target space (Synapse Docs Working Drafts) and a destination space (Synapse Docs final drafts). There is not much else to configure. See the Comala Publishing Cloud docs for more info.
Note that this app can be integrated with Comala Doc Management to automate the syncing step (if desired) after a page is approved. Contact the Comala Support team for help with setting this up.
Viewport (Confluence App)
Scroll Viewport is a Confluence App that allows you to quickly publish Confluence pages in a branded, customizable help website. You write and edit your content in Confluence, structure individual pages into a page tree hierarchy, and then push content to Viewport. Viewport builds a static site from one or more Confluence spaces, preserving your page tree hierarchy as the site architecture.
Setup
Currently, Viewport is connected to the Synapse Docs final draft space in Confluence. Any content placed in this Confluence space will appear on the http://help.synapse.org doc site.
In the future, could explore multiple spaces to one viewport site if programmatic docs migrate to confluence (open API integrations with Confluence?)
links to help docs
Using Comala Publishing with Viewport
When managing the Synapse Docs content and doc process, there are some important configurations to be aware of when publishing content. These configurations impact how internal references in Confluence (like article-to-article links, page attachment links, and includes) are handled by Viewport.
The Viewport app looks for content in a specific Confluence space and publishes that to the web. Viewport’s security settings restrict its own access within your Confluence instance so that for each Viewport site you create, that site can ONLY see content from the Confluence space that is connected to it. Viewport cannot “see” Confluence content from other spaces in your instance.
links
attachments
includes
basically you have to be vigilant because you are the only one who can see the final draft space and that’s the one that needs to be used when creating any sort of internal reference that Viewport picks up.
Troubleshooting
Viewport only sees what is in the final draft space, links to other confluence pages outside of this space won’t translate
same goes for attachments – need to make sure you use the right links for attachments
Includes also need to originate from the final draft space
How to stage changes
For yourself
For someone else on the live site using tags