Starting with ManualWorks 6.0.18, 1branches and pull requests are supported. They let you change content in a separate workspace instead of editing the original chapter directly, then review the changes and apply them to the original chapter.

When you build documents together, there are “changes that feel too risky to make right away.” Adding a new section, substantially rewriting a published help article, or moving several elements are good examples. Fixing a small typo right away is fine, but changes to the structure call for a flow where you work on them separately, check them, and then apply them.

Branches and pull requests are made for these situations.

Work without touching the original chapter

A 2branch is an independent workspace created from a specific chapter. When you create a branch, the content of the selected chapter is copied, and you can freely edit the chapter title and elements in it.

In a branch, you can do the following.

• Edit the chapter title

• Edit element content

• Add and delete elements

• Move elements

• Change element types, custom IDs, and options

Changing content in a branch doesn't change the original chapter right away. So you can prepare changes while keeping published documents, or documents others are viewing, stable.

Review changes in the context of the whole chapter

On the branch screen, you can see the differences between the original chapter and the branch. Instead of just listing the changed elements, it shows which parts were added, deleted, or moved within the whole chapter.

With document changes, looking at the sentences of a single element often isn't enough. The surrounding context, heading structure, and element order all need to fit together. The branch changes screen is designed so you can review with this context in view.

Request a review with a pull request

When you're done, create a pull request. A pull request is a request to apply the work done in a branch to the original chapter.

When you create a pull request, the branch content at that moment is saved as the basis for review. Further edits in the branch aren't included in a pull request that already exists. Reviewers check the changes on the pull request screen, leave comments if needed, and then merge or close it.

Handling conflicts when the original chapter changes

If the original chapter changes after you create a pull request, conflicts can occur. In that case, for each conflicting 3element, choose whether to apply the branch's change or ignore it, and then merge.

Because conflicts are handled element by element instead of overwriting everything, reviewers can compare the latest changes in the original chapter with the branch's changes and apply them more carefully.

Especially useful for these kinds of work

Branches and pull requests work well for the following kinds of document work.

• Substantially revising help chapters for a release

• When several people need to review changes to the same chapter

• When you need to prepare a draft first instead of editing a published document directly

• Checking changes with a big impact if done wrong, such as moving or deleting elements

• Running a review flow where writers and document owners are different people

Each branch and each pull request covers just one chapter. Splitting changes into small pieces makes reviews easier and reduces the chance of conflicts when merging.

For details, see the Branches and Pull Requests chapter.