Customer Spotlight: Upvest

Today we sit down with Geoffrey Teale, Head of Developer eXperience at Upvest to discuss how they migrated their API documentation to Doctave.

You can find Upvest’s documentation at https://docs.upvest.co.

Working with Doctave got us up and running very quickly, without any compromises, and we’ve been very happy with our decision.

A bit about Upvest

Nik: Could you tell us a bit about Upvest?

Geoffrey: Upvest is a fintech startup that provides a B2B API for investments. The tagline we use is “One API, any investment experience”. We allow our customers to build any kind of investment experience with one simple, modern API.

Nik: How is your engineering team structured?

Geoffrey: Currently Upvest is nearly 150 people, of which more than half are involved in product and engineering. The engineering organisation is split into tribes, and my team, developer experience, is one of those tribes. We work mostly in Go, using an event-driven microservice architecture.

Documentation culture at Upvest

Nik: What kind of documentation do you publish?

Geoffrey: Our API is our only product, so documentation is incredibly important for us. The fact that my tribe exists is a reflection of that.

We have a portal that is not just automatically generated API documentation, but also a lot of prose, broken down by use cases. We have tutorials, guides, and other reference material.

We then break down documentation down by versions. Sometimes we will want to share documentation of new functionality with certain customers ahead of its release, in which case we will create a special version for the functionality.

We also break down documentation based on customer use cases and business models, which impact how our users use our API. Our documentation has to reflect that.

Nik: Who is responsible for documentation at Upvest?

Geoffrey: The developer experience engineering falls under my tribe. The team is responsible for technical writing and documentation, among other things. Documentation ends up being around a third of what they spend their time on. The team is 4 people in size.

Nik: You decided to employ a docs-as-code approach early on. Could you talk about that decision?

Geoffrey: We have always taken a clear view that documentation is an important part of developer experience. Making documentation part of the workflow of maintaining software is a fundamental element to me. Documentation should be managed exactly the same way as we manage code. This means versioning and branching docs and code the same way, and the documentation should always match the implementation.

If there is a mismatch between documentation and the implementation, and the customer sees this, we consider it a serious bug. And from the user’s point of view, it’s not clear if the implementation or the documentation is at fault. So we consider bugs in documentation to be as serious as a bug in the implementation.

Documentation should be managed exactly the same way as we manage code.

Docs-as-code is simply the best way for us to ensure the documentation matches the implementation.

Issues faced

Nik: What tools were you using before Doctave? What challenges did you run into?

Geoffrey: We were using an open source static site generator called Hugo. It’s a great tool, but lacked some of the functionality we required.

In particular, the versioning model it uses means we would be tied to one set of documentation in the Git repository, which did not fit how we wanted to do versioning. Deploying multiple versions of that documentation in our cloud would have been costly and complicated.

We could have decided to start investing in Hugo to build the functionality we needed. But that is a resource allocation question - if we could go out and for a reasonable cost get a solution that works, that would be preferred.

It would have been a significant engineering effort to decide to build our own documentation stack

In the end, we are not in the business of building documentation tools. It’s not what Upvest does. It would have been a significant engineering effort to decide to build our own documentation stack, and working with a trusted partner was a much better option to help us get up and running quickly.

Choosing Doctave

Nik: What made you consider Doctave as an alternative?

Geoffrey: There are plenty of documentation tools out there, and we could have decided to start investing in them. We however found that most OpenAPI based tools are quite restrictive in the way they work.

So for me the decision came down to if we could find a good tool that does what we need, is flexible, and at a good price. As opposed to investing the time of our software engineers.

I was with a client last night and they were beaming about our documentation compared to our competitors!

Working with Doctave got us up and running very quickly, without any compromises, and we’ve been very happy with our decision.

Nik: How did the migration of your documentation to Doctave go?

Geoffrey: Going from Hugo to Doctave was very easy, them both being Markdown based tools.

There were cases where we had to convert Hugo shortcodes to Doctave’s syntax, which is similar, but not an exact match. We also had to translate partials to Doctave’s system.

When we did the migration, Doctave was still under heavy development, but today it would be a trivial migration.

Documentation today at Upvest

Nik: How does your documentation workflow look today? Have things changed since choosing Doctave?

Geoffrey: In terms of workflow the biggest impact has been the Doctave desktop app. We have non-technical users that contribute to our documentation occasionally, such as product managers. When we were using Hugo, it was hard for them to set up the Hugo environment on the command line in order to contribute.

Doctave’s desktop app on the other hand is incredibly simple and easy to install. They can download it from our own internal app store, and start contributing very quickly.

Today our public blog is still hosted with Hugo, and the biggest issue we have is being able to get previews working for non-technical stakeholders.

The Doctave dashboard is a great management tool and since we have Doctave integrated with our CI/CD pipeline, we get previews for all changes we make automatically. This has been a positive addition to our workflow.

Nik: Has Git been an issue for your non-technical documentation contributors?

Geoffrey: Some small issues, but mostly people can work fine. We use GitHub and people can get by most of the time, even if they are not engineers.

The biggest issue for us is not Doctave-specific, but actually getting users to cryptographically sign their commits. Beyond that, it has not been an issue.

Nik: Anything else you would like to share?

Geoffrey: Well firstly, we have been incredibly pleased with the partnership we’ve had with Doctave. We got from it everything we could have asked for.

I was with a client last night and they were beaming about our documentation compared to our competitors! Part of the this of course the strategic effort we put into documentation, but it’s also the tooling we use.

Doctave has been an amazing fit for us and we have been super happy with it.