Wultra Blog
Published in

Wultra Blog

How We Built Our Brand New Developer Portal. And Why…

Great technology products do not work unless they also provide a great developer experience. Especially when the technologies are complex and difficult to comprehend, which is the case of digital banking security plugins that we do, the developer onboarding can be a big decision making factor. However, building a comprehensive developer portal is a challenging and never-ending task.

Github Wikis

At some point, a single README.md file with documentation simply became way too long. We also suddenly had more than one repositories. Initially, we used Github Wikis for the documentation of each individual repository. For some time, this worked relatively well. We cannot give Github enough credit for helping us with the development infrastructure. Having a free Wiki with every Github project was extremely convenient.

Use of Github Wikis for per-repository documentation.

Github Pages… ish… Kind Of…

In a poor attempt to tackle this issue, we prepared a lightweight Github Pages project that would link the individual Wiki pages. In our typical ”fairytale hippie graphic design” of that time, we built our first “download portal.”

Use of Github Wikis with an “index” page hosted at Github Pages.

Complex Software, Complex Requirements

It didn’t take long, and we saw that we could not just put a sticker over the bigger issue in the documentation structure we had. We suddenly ended up discussing topics such as:

  • Overview Documentation: How do we document a situation in which several components need to be deployed at the same time, to achieve specific customer setup?
  • Maintainability: How do we make sure that the documentation does not deteriorate (broken links, too loose structure, …)?

Solutions Too Small, Solutions Too Big

We started looking at the options for the developer portal platform. And while it was not the solutions’ fault, we were not really happy with them.

Square Peg in a Round Hole

Building Our Own Developer Portal

Instead of thinking about why our software is wrong, we started to think about what we need from the documentation. We put together the list of basic requirements:

  • The documentation is created naturally alongside the product.
  • The documentation is versioned according to the release.
  • Flexibility — ability to create a new type of documentation.
  • Eye-catching and consistent styling that is easy to read and navigate.
  • Simple updates of current and previous versions.
  • Documentation exports.
  • Maintainability and automation.
  • We will use an in-house-made command-line tool to do the documentation pre-processing and validation.
  • We will compile the pre-processed documentation using Jekyll into the Liquid templates to obtain static HTML documents.
  • We will host the resulting documentation on Github Pages.
{
"repositories": {
"ssl-pinning-ios" : {
"remote": "wultra/ssl-pinning-ios",
"tag": "1.2.0"
},
"powerauth-server": {
"remote": "wultra/powerauth-server",
"branch": "releases/0.24.x"
}
},
"repositoryParameters": {
"ssl-pinning-ios" : {
"singleDocumentFile": "README.md"
}
},
"globalParameters": {
"releaseIdentifier": "2020.05",
"parameters" : {
"docPath": "docs",
"homeFile": "Readme.md"
}
}
}
Use of Jekyll and Github Pages to render the documentation completely.
  • The documentation moved from Github Wikis to the /docs sub-folder in the repositories. This enabled versioning of the docs with the software and included the documentation changes in each pull request review.
  • We fixed a lot of broken links and missing resources.
  • We had a new toy we could be excited about! 😊

A Brand New Developer Portal

One day, we just decided to take some extra steps and launch a new project codenamed “The Brand New.” We took the same technology stack and made everything better.

The reveal of the brand new developer portal.

Introducing The Tutorials

Besides the component documentation, we finally added some general guides and tutorials. We currently do not have many of those, but we can now add them swiftly as the new topics emerge.

Tutorials cover a specific topic, sometimes using multiple tutorial parts (i.e., based on the platform).
<!-- AUTHOR joshis_tweets 2020-05-04T00:00:00Z -->

Per-File Sidebars That Stick With You

In the previous version of the documentation, we relied on the Github Wiki convention of having a _Sidebar.md file in the repository, which results in placing the sidebar on the page. However, this approach had some limitations. We had to use the same sidebar for all documentations in the document folder — there was no way to specify a different sidebar. Also, the sidebar could be very long. It always had to scroll with the document content. Otherwise, we would end up with annoying sidebars that either scroll weird, or make some links inaccessible at the bottom.

<!-- SIDEBAR _Sidebar_Server.md sticky -->
A sticky sidebar makes it easier to jump back and forth in the documentation.

Code Samples With Language Tabs

In typical Markdown-based documentation, we usually ended up selecting a single language for the particular piece of documentation or writing examples in multiple languages below each other, making them harder to navigate. In our developer portal, we use code tabs.

{% codetabs %}
{% codetab Kotlin %}
```kotlin
val result = PasswordTester.getInstance().testPassword("test")
```
{% endcodetab %}
{% codetab Swift %}
```swift
let strength = PasswordTester.shared.testPassword("test")
```
{% endcodetab %}
{% endcodetabs %}
Code tabs allow easier discovery of the topic for multiple platforms.

Full-Text Search

Thanks to a fantastic DocSearch project by Algolia, we quickly extended our developer portal with a precise and beautifully presented full-text search.

Full-text search helps developers find what they need faster.

Accessible Support Channels

Of course, despite our best effort, sometimes reading the documentation does not help. We made the option of reaching out to us on various support channels easy and accessible to everyone.

Accessible support options help to resolve issues and answer questions.

Summary

Of course, we know that we are not done yet. Writing and improving documentation is one of those tasks that never end. We still need to tackle the more advanced issues, such as including the developer success stories, video tutorials, handle the versioning of the components that develop at different paces, prepare better documentation for REST APIs, introduce the FAQ and Troubleshooting sections, and many more.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Petr Dvořák

CEO and Founder of Wultra. Speaker. Author of PowerAuth, QR Platba and 6 mobile banking apps. Interested in #business, #mobile, #tech and #security.