Using Build Previews With Your Team

At Doctave we believe documentation is the responsibility of the whole product and engineering team. This is why we designed Doctave with collaboration in mind.

Uploading documentation to Doctave creates a build. And for every build, we also create a build preview.

Build previews

Every time you upload documentation, Doctave creates a preview environment for the build. In this environment, you can click around just like in your public documentation, and see what your changes will look like.

Build previews are only visible by members of your team, and can't be seen by unauthenticated users.

You can access a specific build by going to the builds page, and clicking on the build preview link:

This will take you to the preview environment, showing you the documentation at that exact commit:

Build previews are otherwise identical to live documentation, except for the banner at the top of the page showing associated metadata, such as Git SHA and branch.

You can go back in time to any build in your history and see its preview environment at any time.

Automatic uploads from CI/CD

We recommend you automatically upload your documentation from CI/CD. This way every change is built and easily shareable with the rest of your team.

It also means that contributors don't have to use upload tokens or install the Doctave desktop app.

We've written specific guides on how to add Doctave to your CI/CD pipeline.

Collaboration workflow

In Doctave we publish documentation changes similarly to how we publish code changes.

Here is the general outline of our workflow:

1. A developer is tasked with writing or updating documentation for a feature
2. They open our documentation in the Doctave desktop app and write their changes locally
3. When they're ready, they create a pull-request and ask for reviews
4. Our CI/CD pipeline uploads the changes, creating a build, and an associated build preview
5. Reviewers look at the changes in the build preview and leave comments in the GitHub interface
6. If there are changes required, we get a new build preview when the pull-request is updated
7. Once the pull-request is merged, CI/CD uploads the documentation from our main branch, which causes the user-facing documentation to be updated