| Table of Contents |
|---|
Overview
| Table of Contents |
|---|
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, 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
...
The Docs Project on Jira is the main tool for tracking Synapse doc issues, tasks, and work in progress. Any work on related to 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, and collaborate on tasks.
SetupBriefly describe 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.
...
The second space, Synapse Docs, is a space for final drafts only and is what drives the http://help.synapse.org doc site. This 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 are 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 any new content or edits to the Synapse Docs site are gated and require an admin review before those changes appear on 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 docConfluence 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.
...
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)
...
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. 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.
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 connected configured to the publish Synapse Docs final draft space in Confluencea 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 to with one viewport Viewport site. This may be desirable if the Synapse programmatic docs migrate to confluence (open API integrations with Confluence?)links to help docsConfluence. 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 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 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 includesInclude macros) are handled by Viewport. The Viewport app looks for content in a specific Confluence space and publishes that to the web.
Our Confluence:Viewport configuration is 1:1
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 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 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
...
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.