Dachary Carey
How do you make technology easier for developers to adopt? Give it good docs! Dive into the evolution of Tugboat’s new documentation site.
We love Tugboat, and we know developers love it, too - when they get everything set up and working smoothly. But our team has lived in Tugboat throughout its evolution, and we know the app inside-out; it’s easy for us to onboard new projects. We wanted Tugboat to be easy for new developers to approach, and one way we knew we could support that is by improving Tugboat’s documentation.
The Tugboat doc site had primarily evolved as our developers wrote things down that they were repeatedly asked to explain in our Support Slack. While it was great and helpful info, it didn’t necessarily bridge all the gaps new developers had when coming to Tugboat for the first time. We wanted to change that; we wanted to make it easy for new developers to follow a simple set of steps to get Tugboat connected to git repositories, and then to set up services to start running Tugboat. But our developers were busy developing - and weren’t necessarily sure how to get from where we were, to where we wanted the docs to go, anyway. So we decided it was time to bring in a technical writer to improve Tugboat’s documentation. (Hi, I’m Dachary. Nice to meet you!)
During our Tugboat user testing and redesign experience, we learned that onboarding was a pain point in earlier versions of Tugboat and competitor products. Our redesign went a long way toward addressing that, but there were still aspects of Tugboat that weren’t intuitive for new users. It was time to invest in new documentation for Tugboat.
When our new technical writer came in, the first thing she did was read Tugboat’s documentation and attempt to create a project in Tugboat. Between the existing docs and the starter code files, it was enough to get started, but there were questions and gaps along the way. She took notes and identified deltas in the documentation. Then, she dived into the Support Slack and other supporting materials, mining those for additional questions and pain-points. The goal for this exercise was to surface the points where developers need more help onboarding and using Tugboat.
After identifying deltas in the documentation - there were no docs about administering users or billing, for example - our tech writer built out a proposed hierarchy for the new documentation site. All of the existing content would stay, but some of it would be moved into a new structure that attempted to better bring the docs to developers wherever they were in the onboarding process. Additional documentation would be created to address the deltas in the existing docs.
The new hierarchy took a task-based approach to using Tugboat, organizing content around steps like Setting up Tugboat, Setting up Services, Building a Preview, and Using Base Previews. In one example, content that was filed under Advanced - a page about Running a Background Process in Tugboat - moved to Setting up Services. The goal was to enable developers to dive into and out of the documentation to accomplish their task quickly, without requiring them to self-select as “advanced” users, or to read a lot of underlying concept content about how Tugboat works.
That content is still there, though, and has been expanded for areas that developers find tricky. The How Previews Work section, for example, now contains more info about the build process, including a flowchart to help users visualize where various processes start in each build phase. The goal was to provide enough information for users to quickly achieve tasks in Tugboat, with more content available for folks who wanted to understand “why.”
With a proposed hierarchy in place, it was time to build out new content for the documentation site. We went through each process and captured the step-by-step instructions to walk users through how to accomplish each task. For visual learners, we’ve added expandable Visual Walkthrough sections to task-based instructions, featuring marked-up screenshots that show you where to find various options on the page.
As the documentation was expanded, and our technical writer went through every process in using Tugboat, we identified areas where additional context or background knowledge might be helpful. That information became callout text peppered throughout the task-based instructions, with links to more information for users who want to dive deeper into the details.
As new content was created, pages began to get longer, and we noticed performance issues with our underlying infrastructure - a legacy GitBook install, which had been officially deprecated and was no longer supported. Moving to GitBook’s cloud-based solution was a no-go; we preferred to keep our docs in a versioned git repository and use a docs-as-code workflow; so we considered other static site generators. We wanted to maintain documentation that developers could easily contribute to, and make it easy to file issues for gaps in the docs.
After a brief look around at the current options, we landed on a Hugo as a possibility. We selected a theme that worked well with documentation, and our technical writer put together a fast-and-dirty proof-of-concept of a couple of pages built in Hugo. It was quickly apparent that Hugo checked a few important boxes:
Boxes checked, we decided to move forward, and less than a week of work saw the Hugo migration complete.
With lots of new content, and a faster, better-looking documentation site, we wanted to get the new docs into developers’ hands. Tugboat’s principal developer Ben Chavet gave the new technical content a thorough technical review, and CEO Matt Westgate sorted out a few typos, giving the new docs site a thumbs-up for release. After a final flurry of cleanup and launch-related activity, the new docs site was ready to publish.
We’re happy to note the new documentation site has been getting lots of views, and has successfully answered questions for folks in Tugboat’s Support Slack. We’ve identified a few areas to expand, based on feedback from folks in the Support Slack, and are working with our developers to build out more content for the site. Meanwhile, we hope you find the new documentation helpful, and the redesigned site easy-to-use!
Our documentation remains an open-source project; we welcome contributions or issues via our GitHub repo.
Tell us about your project, schedule a demo, or consult with a Tugboat Technical Account Executive.
