Collaboration Tools

Creating and publishing content is often a collaborative exercise, and Atlas makes it easy to work together on a project, track everyone's changes, and incorporate those changes into a master set of project files. Here is an overview of how you can use Atlas to leave behind Word file wrangling for good.

Adding New Collaborators

To grant others access to your project so that they can edit the text or generate PDF, EPUB, Mobi, or HTML builds, you will need to add them as collaborators. To do so, navigate to your project, and click on the Project Settings button. Then, in the Add New Collaborator section, enter the email address of a person you wish to add to the project. You'll see two types of collaborators to choose from:

  • Owner - can edit any branch in the project, review others' submissions, merge to master, and invite additional collaborators
  • Collaborator - can only edit his or her own branch and must submit changes for review by an owner to merge to master

Choose the appropriate collaborator type from the drop-down, and then click Invite. Repeat for each user you’d like to add.

If an invitee is already an Atlas user, she will immediately be granted access to the project and see it on her Projects dashboard. If she is not yet an Atlas user, Atlas will send her an email asking her to sign up, and once she does so, she will see the project on her Projects dashboard.

Working in Branches

Branches are an important and powerful feature of the Atlas collaboration suite, as they allow users to work independently and concurrently without worrying about disrupting others' work or introducing file conflicts.

In Atlas, the master set of files is stored on the master branch of the project. This is usually the canonical version of the project. If a user wants to edit the project content, he should click "Add a branch" to create his own branch—a personal copy of all the files in the project. When he has completed his work, he'll submit the edits he has made on his branch to a project owner, who reviews the changes and decides which ones to merge back into the master branch to become part of the master file set.

Anyone using Atlas can make her own branch to edit files, and there's no limit on how many collaborators can have branches at once. But only collaborators with Owner status have the ability to make changes directly to the master branch and the power to review, accept, or reject changes from others. (Owners can also make their own branches, if they'd rather not make changes directly to the master branch.)

Can I Edit the Master Branch?

If you're an Owner on a project, you can edit the master branch directly, or create your own branch. This is what you'll see if you have permission to work directly in the master branch:

Alt Text
Figure 6-1. Note the unlocked icon in the upper left corner.

If you're a Collaborator, you won't be able to edit master. Here's what you'll see:

Alt Text
Figure 6-2. Note the locked icon in the upper left corner.

You'll need to make your own branch to edit the project files, as described in the following section.

Creating and Selecting Your Own Branch

To create your own branch, click on "Add a branch" in the upper-right corner:

Alt Text

Here's what you'll see after clicking "Add a branch":

Alt Text

The new branch is labeled with your username (e.g., "dangmail" in the upper-left corner, as shown above). To switch between branches, use the dropdown menu, as shown here:

Alt Text
Note

Even if you can't edit master, you can always view it for reference.

Comparing and Submitting Changes to Master

After creating a branch, you are free to make any kind of change, including adding or deleting files, fixing typos, adding new images, or inserting comments

You can compare the modified files in your branch against the files in the master branch by clicking on "Compare," which is right under the "Send Edits to Master" button. If you're satisfied with the changes you've made, you can then send the edits to master so that the project owner can review them. The following two sections cover each of these steps.

Alt Text

Comparing to Master

The Compare tab allows you to compare your revised project files against those in the master branch before you submit your changes for review. Make sure that you're on your branch, and then click on "Compare" after you've made some changes. You'll see something like this:

Alt Text

In this screenshot, you see the changes in your branch compared against master. Text that you've deleted is highlighted with a red background, and text you've added is highlighted with a green background. Here, the text "Is" has been changed to "is", and the text "Heading" to "heading."

The asterisk icons indicate changes that can't be displayed visually, such as new lines or returns. You can switch to the Code Editor to see details on the markup changes that have been made here.

Sending Changes to Master

Once you're happy with the changes you've made, you're ready to send them to the project owner for review.

If you're already in the Compare view, you can submit your changes by entering a description summarizing the revisions you've made in the "Send Changes to Master" dialog, and then clicking the Submit button, as shown below:

Alt Text
Warning

If you send changes to master for review, be aware that the entire branch is sent, not just specific files. The Owner of the master branch will see and review all of the changes that you've made in every file in your branch—so organize your workflow accordingly.

You can also send changes to master for review from the project dashboard by clicking the "Send Edits to Master" button. This will take you to the Compare tab, where you can fill out the "Send Changes to Master" dialog and submit as described above.

After submitting your changes for review, you'll see a confirmation, which looks like this:

Alt Text
Note

Note that after you submit your changes to the master branch, your branch will no longer be available. To make more changes, create another new branch!

Review and Merge Changes

Only collaborators with Owner status can merge edits into master. If you are an owner, you can see if there have been any revisions submitted for review by going to the dashboard, navigating to the master branch, and looking at the Review button, which will indicate the number of pending merge requests. In the example below, two sets of edits have been submitted by Collaborators for review:

Alt Text

Click on "Review" to reveal more details for each merge request:

Alt Text

In the above example, there are two review requests (both from the same Collaborator). To review a set of changes, click on the corresponding "Review changes" button.

Alt Text

As in the Compare view described in the previous section, deleted words are shown in red, additions are in green, and changes that can't be shown visually are indicated with asterisk icons (again, for more details on the markup changes flagged by these icons, switch to the code view). 

Note the up and down arrow buttons, and the Accept and Reject buttons to the right. To navigate sequentially through the edits in the document, use the arrow buttons; the up arrow takes you to the previous edit, and the down arrow takes you to the next edit.

The edit you're currently reviewing will be highlighted in bright red/green. To accept this edit, click the Accept button. Alternatively, to reject the edit, click the Reject button. If you'd like to make additional changes to the document while accepting and rejecting changes, you can also edit the text in the document directly, just as you can when working in the standard edit mode. 

To save time, you can also decide to accept or reject all outstanding edits in a given document at once by clicking either the "Accept All" or Reject All" links below the Accept/Reject buttons. 

Repeat this process for each document that has changes available for review (click the chapter buttons to the left of the editor window to navigate among documents). Once all changes have been addressed by being accepted or rejected, a "Save & Finish" button will appear: 

Alt Text
Figure 6-13. Click "Save & Finish" to merge your approved changes to master

Click this button to merge the changes you've approved, as well as any other edits you've made during the review process, into the master branch, and make them part of the master file set.

Warning

Once you begin accepting and rejecting items in a particular merge request, you must complete the review and click "Save & Finish" or cancel. Partial progress on the review screen is not saved if you navigate away from the review page without clicking "Save & Finish."

Comments

Sometimes you just want to ask your fellow collaborators a question rather than making a text change, or maybe you're a copyeditor that wants an author to include more detail; Atlas comments are a great way to do it.

To insert a comment, simply click the button in the toolbar.

Alt Text
Figure 6-14. An Atlas comment

Collaborators can leave comments in their own branch, and they'll get sent to an owner in a merge request. If you're an owner, you can leave comments in anyone's branch or directly in master.

To remove a comment, just click the "x".

Activity Log

When multiple people are working on a project it's helpful to know what other people are doing, and Atlas can help with that. Click the button at the top-right of your project dashboard, and you'll see a log of everything that has been happening on the project lately:

Alt Text
Figure 6-15. A project's activity page

On the right, you'll find a list of recent builds, who initiated them, and when. You can also download the output formats directly from here, or view the build log for each build.

The left-hand pane displays when collaborators have made changes, which files were changed, and in which branch. You'll also see when merge requests are made and when they are reviewed and accepted into master. This information can help you keep track of what others are working on, and when various documents were last edited.

Best Practices

Atlas's collaboration tools work best when paired with effective communication and organization among collaborators on a project. Below you'll find some suggestions, tips, and tricks from the Atlas team to help you create and manage a successful workflow for your Atlas projects.

Workflow

  • Avoid reviewing and merging more than one collaborator submission at a time. While projects may have multiple owners, designating one person at a time to review submissions and merge them into master will streamline your workflow and prevent wasted time resulting from multiple people reviewing the same submission concurrently.
  • Coordinate who is working on which documents within a project at a given time. The more people working on the same document at once, the more difficult review can become for the project owner. Use the Activity log to help keep track of who is doing what to reduce user headaches!
  • Opt for multiple smaller submissions rather than fewer large submissions when possible. Along with descriptive messages, submitting changes for review in smaller chunks allows the master file set to be updated more frequently, keeps other collaborators up to date, and reduces the chance of multiple collaborators making contradictory changes.

Using the Tools

  • Swap to the code view as needed when on the Compare or Review screens. Not all changes can be represented in the visual view; some things, like underlying markup/formatting changes, are represented in the visual view by an asterisk icon. Just as in the editing environment, you can switch to the code view to view changes that would otherwise be hidden in the visual editor.
  • Add a descriptive message when submitting your changes for review. While these notes are optional, it's useful to keep track of the kind of work contained in each submission to master. It helps eliminate confusion and increases efficiency when merging.
  • Work directly in master when appropriate. Are you starting a new project by yourself, or are you the only owner on a project? You can save time by working directly in the master branch. Atlas will still keep the full history of your work and display updates in the Activity log when you make changes.
  • Use "Accept All" or "Reject All." These features are available on the Review screen and can be used to save time if you're sure you want to accept or reject all of the changes in a given document.
  • Make additional edits while reviewing. Reviewing someone else's changes and notice an additional error? You can place your cursor in the Review window and edit directly. If the section you'd like to change is already highlighted, you must accept or reject the change first, and then you can make additional adjustments.
  • Ask collaborators to set up an avatar. This makes it easy to identify at a glance who has created which builds, left text comments, etc. Set this up from your account settings page. Atlas uses Gravatar, so if you already have an account under your Atlas account email address, you're already done.