Synapse Docs Administrators Guide
- Stacey Taylor (Unlicensed)
- Bruce Hoff
Overview
This page is for Synapse docs administrators, and it describes the processes and tools used to manage the Synapse Docs website (help.synapse.org/docs). An administrator's responsibilities are:
Manage the Jira DOCS project and triage incoming requests and issues
Collaborate with subject matter experts on new docs and/or edits to existing docs in Confluence
Manage the review and approval process for all edits to the docs
Verify that content is formatted and referenced correctly so that Viewport can publish it, and provide ultimate approval for all changes before they become final
Sync approved content from the working draft space to the final draft space, and update the Viewport site to incorporate new content
Before you read this page, make sure you have read the Synapse Docs Contributor Guide for detailed step-by-step instructions for how to use many of the tools described in this article.
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. Tools in the Synapse Doc toolchain are:
Jira
Confluence Cloud
Comala Publishing App for Confluence Cloud
Comala Doc Management for Confluence Cloud
K15t Scroll Viewport for Confluence Cloud
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 related to Synapse docs must be recorded in a Jira ticket so that we have one place to collect issues, see all upcoming/current work, and collaborate on tasks.
Setup
The DOCS project is set up so that all incoming tickets are automatically assigned an “Open” status. Once they are reviewed, tickets can either be assigned as Backlog, Selected for Development, or In Progress. Once complete, tickets are moved to a Closed status.
Anyone can open a Jira ticket in the DOCS project, and contributors can assign an issue to themselves if they wish to make the edit. Otherwise, tickets should be left unassigned and the administrator will assign them as appropriate and move the tickets to the appropriate status as the work progresses.
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. Think of this space as the production site for http://help.synapse.org . Finalized, approved pages from the working draft space are copied to the final draft space where they can be published with the Viewport app (see below). 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.
It is highly recommended that administrators watch all pages in both the working and final draft spaces so that they are notified of any changes to either. Theoretically, there should be no changes to the final draft space since this space is not visible to anyone but the administrator.
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 approve 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 this or any other Confluence space in our instance. An approval process is necessary so that new content or edits to the Synapse Docs site are gated and require an admin review before those changes are merged with 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 Confluence page, and it also creates a Workflow Report dashboard where administrators can see the review/approval status of every document in a particular 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.
In the future, you may wish to create a custom approval workflow that incorporates an additional status from those shown above. This additional status could be an “exempt” category for articles that only ever reside in the Working Draft space and should never be synced to the final draft space. This status would be applied to all documents in the README section, so for example the Style Guide, Contributor SOPs, and this document.
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). Syncing a page from the target space will copy all content, page labels, and page history into the destination space. Note that this is a unidirectional behavior, and you can cannot sync changes “in reverse” or upstream from the final draft space to the working draft space. Therefore, any changes made in the final draft space will be overwritten the next time that page is synced from the working draft space.
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 or see the Comala Publishing Cloud docs for more info.
NOTE: To change content and publish, one not only needs edit permission in the upstream Confluence space but also in the downstream or “target” space. Visit the target space, choose Settings > Space Permissions, and then add the individuals or groups who you wish to have the ability to publish.
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.
You can create multiple, independent Viewport sites from as many Confluence spaces, and you manage them all in one Viewport dashboard. To view that dashboard, go to Apps → Viewport in the top menu on any Confluence page. If you do not see Viewport in the Apps menu, ask IT to add you as a Confluence administrator, OR ask a Jira sys admin in IT to add you to the group scroll-viewport-admins.
Setup
Currently, the Viewport app is configured to publish Synapse Docs final draft space in a standalone Synapse Docs help site at help.synapse.org. Any content placed in this Confluence space will appear on the http://help.synapse.org doc site.
The look and feel of the Synapse Docs website is somewhat configurable using the Viewport theme editor. From within the editor, you can select different layouts, logos, colors, and configure the header and footer links. You can also inject custom CSS if you want to style the site further. For instructions on how to access the theme editor as well as what elements can be changed, see the Viewport help docs.
As mentioned above, currently the Viewport app is using content from one Confluence space (Synapse Docs final drafts) to publish the Synapse Docs help website. In the future, you could explore the option to link multiple Confluence spaces with one Viewport site. This may be desirable if the Synapse programmatic docs migrate to Confluence. Confluence integrations for Swagger/Open API exist, and may be potential options for uniting all of our Synapse doc sites (Python, R, Command line, REST API) into one consistent brand.
The Viewport help docs for Confluence Cloud are helpful and informative, and it is HIGHLY recommended that any Synapse docs admin become intimately familiar with these. The Viewport support team (help@k15t.com) is also extremely helpful and responsive with questions.
Using Comala Publishing with Viewport
When managing the Synapse Docs doc process, there are some important configurations to be aware of when publishing content. These configurations impact how internal references in Confluence (article-to-article links, page attachment links, and Include macros) are handled by Viewport.
Our Confluence:Viewport configuration is 1:1
Viewport’s security settings restrict its access within your Confluence instance so that for each Viewport site you create, that site can ONLY publish content from the underlying Confluence space that is connected to it. For example, if represented conceptually, our Viewport configuration in Confluence would look like this:
In this diagram, the community doc websites are represented in pink and green. There is one Confluence space for each community, and each space is attached to its own Viewport site. Viewport can publish content from Space A on website A, but it cannot publish any content from Space B, C, D, or E on site A.
Similarly, the Synapse Docs configuration is represented by the white and yellow shapes. Even though the content in Space C and D is identical because we are using Comala Publishing to sync pages, Viewport will only publish content that resides in Space D to website D. This is important to remember as you read the next sections.
Note: as mentioned above you could connect multiple spaces to a single Viewport site. For example, you could connect Space A and Space E to Site A in the diagram above. In that case, Viewport would be able to publish content from both spaces, however, all of the content from Space A and E would be styled and branded the same on Site A. The reason we have set up a 1:1 relationship between spaces and Viewport sites is because we want different branding for each of our Viewport help sites.
Viewport converts internal Confluence references automatically
The Viewport app looks for content in a specific Confluence space and publishes that content to the web. Importantly, Viewport can detect internal references within a Confluence space, such as links to other articles in that space, URL links to page attachments, and content within include macros. Viewport will convert these items to external-facing Viewport references automatically.
For example, if you are writing an article and you create a link to another page within the same Confluence space (e.g. http://sagebionetworks.jira.com/wiki/spaces/XYZ/pages/PageID), then Viewport will convert that Confluence page link to the corresponding Viewport page URL (help.synapse.org/docs/PageTitle/PageID) when you publish the page.
Similarly, if you use an include macro to reuse content across multiple pages in one space, as long as the included content resides within the same space, Viewport will publish it.
Critically, if you link to a Confluence page that is in a different space and not connected to Viewport, then Viewport will not convert the link. Instead, it will retain the http://sagebionetworks.jira.com address, and this link will direct your Viewport audience to our Confluence instance, likely to a restricted page. Similarly, if you use an include macro to reuse text, but the source of the include macro is in another space not connected to your Viewport site, your included text will not appear when you publish.
Comala Publishing does not convert internal references
When Comala Publishing syncs page content from Space C to Space D, it does not convert internal Confluence references. For example, a link to an article in Space C will remain pointing to Space C after it is synced to Space D. When Viewport publishes Space D, Viewport will not convert that link because it is outside of Space D.
What does this mean for Synapse docs? You as an administrator must ensure that any Confluence references used in the Working Draft Space are pointing to the Final Draft space:
Internal links to other pages: Because contributors cannot see the final draft space, they cannot add links to those pages when they edit in the working draft space. If contributors need to reference another Synapse Docs article, they should either use the external-facing Viewport link (help.synapse.org/docs/PageTitle/PageID) in their Confluence page OR indicate that an admin needs to create a link for them that points to the appropriate final draft page.
Links to download page attachments: Similar to page links, you can generate a URL that points to a Confluence page attachment for download. This URL needs to be copied from the final draft page, not the working draft page. To set this up, you need to create the working draft, attach the file, sync the page to the final draft space, go to the final draft space to grab the attachment URL, then go back to the working draft page to insert it into the page text.
Include and excerpt macros: Include and excerpt macros must originate from within the final draft space, meaning that only you as an administrator can add them to a page. There is an include library in the final draft space that contains reusable text for article footers, and this content is what should be referenced whenever a new article is created in the working draft space.
Resources
Viewport Help Docs : bookmark this to make sure you always land on the Confluence Cloud version of their help docs, not Confluence Server
Comala Publishing Help Docs : This is a new app, so these docs are in their infancy. Generally, contacting Comala support for help with this app has been more fruitful.
Comala Doc Management Help Docs : again, bookmark this to make sure you always land on the Cloud version.
Rock the Docs (from K15t, who make Viewport): Best practices for managing collaborative documentation in Confluence
Abigail Sutherland - Organizing a Confluence hoard, or, does this page spark joy? : a video on how to organize a Confluence instance across an organization
How to Make Sense of Any Mess: Information Architecture for Everyone : a good book on information architecture for anyone who is interested
Write the Docs Slack : Recommend the #confluence and #doctools channels. The #confluence channel is very active, and you will see many posts from K15t (Viewport) guru Matt Reiner.