How Trunk keeps documentation up to date by syncing it with their Git repo

Trunk is a dev tools company that builds engineering velocity software. And with such a strong focus on developers, they understand their audience well enough to know that what they really care about is the details.

“Our marketing site is for product-focused people,” explains Eli. “But most engineers will look right past all that and head to the docs for the nuts and bolts. So we invest heavily into making sure our docs are detailed, inviting and modern.”

For Trunk, that of course meant packing the documentation with useful information — but the team also wanted to give readers a great experience. They needed powerful customization options, as well great version control and a safety net when they need to make bigger changes across all their pages.

Moving from ReadMe to GitBook

“We were using ReadMe for all of our documentation,” says Eli. “The design left a lot to be desired — I think visually it feels quite stale.” Beyond the visual design, the team also found that they couldn’t do basic things that they expected, like adding tabs to explain different processes and workflows.

But the Trunk team also struggled when it came to keeping track of changes. “ReadMe has a custom versioning concept that made it really hard for the team to update documentation,” Eli tells us. “People would be in the wrong version, or people would create a new version with new edits, but they wouldn't back-fill into an old version. We were constantly like, ‘where are we at?!’.”

Staying in sync and in control with GitBook

To overcome these challenges, Eli and the team moved their documentation over to GitBook. Not only did our recent customization improvements help them create beautiful, branded docs — our two-way Git Sync also helped them work on bigger changes right from their repo.

“I love the ability to go in and edit locally through the WYSIWYG editor,” says Eli. “But then when there are large changes, I can go in and bulk edit with my IDE, and do a global search and replace.” Of course, with Git Sync, those changes automatically appear in the team’s GitBook docs, too, so everything stays up-to-date. “That's super powerful,” asserts Eli.

But the team made Git Sync even more powerful by combining it with the tools they built using Trunk itself — a series of custom linters to check their documentation before it goes live. Those linters check for live links, dead links, formatting errors, SVG compression and more. “We run all that using Trunk on our own GitBook. It’s really an awesome way to keep the documentation efficient but in a way that’s still nicely presented.”

Powerful customization and fast onboarding

Presentation, of course, is a big deal for Trunk — which is why Eli and the team appreciate how much they can customize their GitBook docs. “I think so much of the stuff I care about is the presentation layer,” he tell us. “How do I set the Favicon for my site, for example? I think GitBook has the right ethos — ‘let’s make sure that this stuff looks beautiful‘.”

Trunk uses cards, code blocks and more to create beautiful-looking docs in GitBook.

The best part? Getting the rest of the team on board was a breeze. “I basically just said, ‘Okay everyone, we’re using GitBook, here you go.‘” laughs Eli. “And everyone was able to jump in and start making edits instantly. I think that’s quite telling — if engineers can just pick up a thing and start using it, then that’s a big deal.”

Next up: moving technical knowledge from Slite to GitBook

The team had their docs up and running in no time, and now their linters check big changes they make for consistency and accuracy. The docs feel more branded, thanks to nicely-designed cards, and any technical changes the team need to make can go through either a change request in GitBook or a pull request in GitHub. So what’s next for the Trunk team?

“I want to consolidate all of our documentation — both internal and external,” says Eli. “So I plan to move the entire company from Slite onto GitBook. I’d rather have one solution for everything.”

→ Get started with GitBook for free

→ Discover GitBook’s customization options

→ Make your documentation process more collaborative with change requests