Synapse Docs Contributor Guide

Overview: How does the Synapse Docs website work?

Scroll Viewport is a Confluence App that allows you to quickly publish Confluence pages in a styled 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. This page is for anyone who wants to flag an issue or contribute edits to Synapse Docs.

Below is a schematic describing how Confluence and Viewport are configured to publish the Synapse Docs website:

Open

1. All drafts are edited, reviewed, and approved in a Confluence space for working drafts, called “Synapse Docs (Working Drafts)”. Think of this space as a kind of staging area for all Synapse Docs content. You are currently reading this doc from within this draft space.

2. Once an article has been edited, reviewed, and approved, an admin syncs the final draft to a second Confluence space for final drafts.

3. This final draft space contains only the finished versions of every article in the Synapse Docs library. This Confluence space is hidden to everyone except administrators to avoid confusion; keeping all working drafts in one space and all final drafts in another allows us to separate what is ready to publish and what is not.

4. Content in the final draft space is built into a user-facing help website using the Viewport app. When an admin triggers a new build, Viewport pulls all content from the final draft space and creates a static site.

How do I contribute?

To flag an issue or request a change to Synapse Docs, follow these steps:

1. Open a Jira ticket at link it to the Synapse Docs project. Specify the doc location, describe the issue, and suggest a fix.

2. Leave the ticket unassigned if you want the ticket triaged and managed for you.

3. Assign the ticket to yourself if you want to make the fix. Find the relevant page in the Synapse Docs (Working Drafts) space and edit the page by clicking the pencil icon (). Publish your changes to the page with a version comment describing your updates. When you are done, click the Review button at the top of the page and assign an administrator (Stacey or Ryan), who will review and approve your changes and then push them to the live docs site.

For more detail and step-by-step instructions with screen caps for each of these steps, see the sections below.

Open

File an issue in Jira

To flag an issue or contribute directly to the docs, create a Jira ticket in the Docs Project. Your ticket will be triaged depending on the nature of the issue. For larger projects like major re-writes or new articles, you will be tagged to contribute directly in Confluence.

In the ticket description, you must include:

• Specify the location: Provide a link to the relevant article or section where you want the change made.

• Describe the problem or change: Write a detailed description of what is wrong or what needs to change. Screen caps are helpful.

• Suggest a fix: Propose a solution or describe how the issue should be addressed. If you are proposing a new topic (such as a new feature), include links to internal docs with information about that topic/feature (user stories, feature requirements, etc). The more detail you can provide, the faster your issue will be triaged.

If you would like the issue to be triaged and managed for you, leave the Assignee field as Unassigned. Note that you may still be asked to contribute to the fix if you are a subject matter expert.

If you would like to make the changes yourself, assign the ticket to yourself and follow the instructions below to contribute directly in Confluence.

Edit directly in Confluence

Depending on the nature of your Jira ticket, you may be assigned to contribute directly to the docs in Confluence.

• Go to the Synapse Docs (Working Drafts) space and locate the article you want to update.

• Switch to edit mode by clicking the pencil icon () in the upper right toolbar.

• Make your edits. Refer to the Style Guide and the How To sections below for help with how to write content.

• To save your edits, click the three dots () in the upper right toolbar and select Publish with version comment. In the resulting pop-up, add a description of what you changed and click Publish. Note this action does not make your content publicly viewable yet, it is only viewable internally on Confluence.

Requesting approval in Confluence

When you are ready for your content to be approved and sent to the Viewport site, click the Review button at the top of the page, then select +Add Reviewer.

Add a Synapse doc admin (required) and anyone else who should review the content (optional) and approve the doc.

If additional changes are needed, you will work with your reviewers to address any remaining issues and then repeat the approval request process.

Once approved, your doc will be synced with the final draft space by a space admin. Your changes will be incorporated with the next build of the doc site.

Granting doc approval in Confluence

All edits to Synapse docs require approval from an admin, however you may be selected as an additional reviewer if you are a subject matter expert on the topic in question.

If you have been selected as a reviewer by someone else, you will receive an email notification that your review has been requested in Confluence. Follow the link in the email to view the Confluence page.

Review the document. If you have comments, highlight the relevant text and select Comment from the pop-up window.

If you are satisfied with the document, click the Review link at the top of the article page and select Approve. If you are unsatisfied, you can Reject the document, but be explicit as to what changes are needed.

If you or anyone else makes edits to the document after requesting approval (e.g. you enter the Confluence editor and change the text), the approval workflow will automatically revert back to a draft state, canceling the approval process, and you or someone else will have to re-request approval to move your document forward.

Special Cases

Deleting Content & Redirecting

Once a page is deleted in Confluence, its URL is no longer valid. You won’t be able to redirect from deleted content. To work around this, leave the existing page as an interstitial page and include a link to the new content as such (suggested text):

“This is not the content you’re looking for. The content you want is over here <link to new content here>.”

Confluence How To’s

Inserting and removing images

Use the editing toolbar in Confluence to insert images into your articles. Confluence will automatically add each image as an attachment to the page in addition to embedding the image in the article.

To remove an image, click on the image and use the trash can icon to remove the image from the article. Doing so will also remove it from the attachments list.

Image naming conventions

If you are inserting a screen cap of the Synapse UI, name the file with a description of what image is showing, spaced with hyphens. For example, use report-violation-footer.png for an image of the Synapse footer showing where to find the link to report violations.

Changing image size

You can resize images within Confluence by dragging the edges of the image once you have embedded it on the page. However, these changes will not be reflected on the live Viewport site. To change the size of an image as it appears on the Viewport size, you must resize the image file itself. For more on resizing images see the Scroll Viewport help docs here.

Adding links to other articles or sections

To add a link to another Synapse docs page or section, go to http://help.synapse.org/docs and locate the article or section of interest. Copy the URL from that page, or copy the link next to a specific section heading. Paste this link into your Confluence page using the Confluence link editor ( ) in the editing toolbar.

Adding downloads and attachments

• To add a download link to a page (e.g. a pdf, template, or other file that users need to download), add your file as an attachment to the Confluence page. From the main page view (not the Confluence editor), click the three dots at the top right of the screen and select attachments from the dropdown:

• Upload your files.

• In the Attachments view, right click on the name of the attachments and select Copy Linked Address.

• Go to your page and add a link to the desired text. Paste in the attachment link as the URL. Viewport will render the Confluence URL into a file download for external users.

• Note: Viewport can only render links for items that are within the associated Confluence space. Items outside of that space (links or attachments from other spaces) will not render correctly on your Viewport site.

Macros

There are many macros available in the Confluence editor to style a page and add functionality to a Confluence space. The Scroll Viewport app can render some macros, but not all. Viewport also has many features built in to its layouts that make many popular macros redundant (e.g. Viewport automatically creates a table of contents for every article), so in many cases the use of additional Confluence macros on the page is unnecessary. In general, unless directed by a doc admin to use a macro, avoid using them in articles destined for a Viewport site.