Make your documentation process more collaborative with change requests

Change requests in GitBook help your whole team contribute to the documentation process — and we’ve just made them better than ever
Here at GitBook, we always want to give you the best experience possible when it comes to creating and publishing documentation together with your team. And we’ve always believed that a change request workflow is at the core of that collaborative process. That’s why they’ve been a part of GitBook since day one.
Change requests are a great way to make edits to your work, collaborate with others, and keep everything in sync, before merging your changes with your published content. It doesn’t just give you peace of mind when editing live content — it brings more people into that process, and helps you get feedback in context.
We’re excited to share some recent improvements we made to change requests in GitBook below. But first, let’s explore them in a little more detail, and find out why we’re so passionate about them.

What is a change request?

At its core, a change request is a copy of your main content. It comes from the simple concept of branching, which lets you work on multiple copies of the same object in parallel — while keeping the original version intact.
Let’s say you’ve created some internal documentation about best practices in the workplace, and shared it with your team. It’s already live for everyone to see — but by using change requests, you can make a copy, edit the content, get feedback, and iterate. All before merging the changes back into your live pages.
Change requests help you and your team mates collaborate and approve each others work before it goes live.

GitBook: built with change requests in mind

Developers have been collaborating using a branching process for decades — GitHub just helped make it mainstream. So when we created GitBook, we took learnings from that process, and applied them to content and documentation management.
Ultimately, we want to make it as simple as possible for everyone in technical teams to collaborate and create documentation using GitBook. And that’s why you can work together in GitBook just like you do in GitHub or GitLab.
This approach has some major benefits:
  • Lower barrier to entry – Because you can make a change in a branch, people don’t need to worry about their changes instantly impacting the main content. And that empowers more of your team to contribute their ideas, without the fear of accidentally making changes live.
  • More control over your content – You can always be sure that someone with the right permissions has reviewed a change before you merge it into the main content.
  • A place for every change – Multiple people can make concurrent changes, so everyone can focus on their own work — whether their change is big or small. And if there are any conflicts, you can resolve them at the end of the process, when the work is ready to go live.
Ultimately, we believe that developers’ asynchronous workflows are the future for knowledge sharing. That’s why we want to give everyone the tools to support this more inclusive process — and empower everyone to become a contributor, while keeping the quality of content high.

New change request improvements

With all that in mind, we’re excited to share some recent improvements we’ve made to change requests in GitBook.
While change requests are ideal when you have lots of edits running in parallel, we know that with so much going on it’s often useful to see everything at once. So we’ve made it easier for you to focus on what’s most important, with new notifications and a better way to view the change requests that matter to you.

Get notifications and follow up

First, if you’re working with a team, reviewers will also receive a notification when someone sends a new change requests for review. So the right people see updates instantly, improving your collaborative workflow.
We’ve also added a Follow up tab to the Change requests panel. Here, you can keep track of the change requests that are most important to you. You’ll also see the number of open comments in each one, so you can easily resolve them before merging them into your main content.
A screenshot of the Follow up tab within the Change Requests menu in GitBook. There are two change requests in the list, and above them is a section allowing you to create a new change request.
The Follow up tab shows any change requests you’ve added or commented on, plus those in review.

Comments move closer to your content

Feedback is at the heart of any collaborative workflow — and now it’s easier than ever with a new Comment panel that sits right next to your content. So you can view your comments and content at the same time, referencing feedback and leaving replies without having to jump between views.
A screenshot of GitBook showing the Comments panel on the right-hand side, with one comment and the related block highlighted.
Click a comment and you’ll jump right to the block it refers to on your page, so you can see feedback in context.
Talking of improving your workflow, you can also comment on specific blocks in your content. This means editors can easily jump right to the block you’ve left feedback on by clicking the icon next to the page name.

See inline changes with the new diff view

One of the most important parts of a change request workflow is seeing the differences between two drafts of a document. Seeing what’s changed before you merge — or to revisiting a previous change request to see the page history — is essential.
With diff view in GitBook, you can easily see which pages have changes and which haven’t been touched, just by glancing at the table of contents. By default, you’ll now see a + next to pages that have changes, so you can quickly jump in and start your review.
A screenshot of GitBook showing the limited diff view. There are small icons next to some of the pages in the left-hand panel to show the pages that have changed.
By default, you’ll only see icons next to pages with changes when you view a change request.
Want to see a block-by-block breakdown of what’s changed on each page? Hit the toggle and you’ll get a full diff view for your content — giving you more context for your review.
A screenshot of GitBook showing the full diff view. There are icons next to pages in the left-hand panel, but there are also icons on the page itself to show the blocks that have been added or changed.
Hit the Diff view slider in the top-left to view the full diff view — showing changes on the page itself, too.
These changes are just a small selection of the improvements we have planned for change requests in the next few months. We hope you like them — stay tuned for more! In the meantime, take a look at our Changelog to see all our recent updates.
Got questions? Our GitBook docs should help with most of them. If you can’t find an answer there, feel free to get in touch at [email protected] 💌