Tech

Rethinking Our Documentation Experience

John Ngo

We recently launched our new Documentation Hub, a complete rethinking of our documentation experience. UX Designer John Ngo shares the design thinking approach that enabled a small, cross-disciplinary team to understand customer problems, explore the solution space, and ultimately deliver a foundation for shortening the distance between the user interface and documentation.

Old and New Comparison The old and new documentation hub.

For a platform that brings geospatial data and analytics to the developer community, a great developer experience — and by extension, documentation — is a key element in fulfilling that promise.

In the two years since we launched UP42, our documentation had grown to over 100 pages of content. Our API, SDK, and other technical references were scattered across different websites. As a result, our customers were beginning to feel the pain of a documentation experience that was struggling to help them accomplish their tasks and failed to provide insights into the broader capabilities of the platform.

At that point in time, our product had evolved significantly, and our marketing website had already undergone a full redesign. However, despite having grown substantially content-wise, our documentation felt stagnant and dated — unbefitting for a developer-focused product.

Understanding the Problems

Design Process

Kicking off the project, we adopted the design thinking ideology and process popularized by David Kelley and Tim Brown of IDEO. In practice, design thinking is a hands-on, user-centric approach to problem solving that is well suited to small, multidisciplinary teams looking to apply the creative design process to business problems.

Design Thinking An overview of the design thinking process

To start with, we wanted to gather as much feedback and observations as we could get to form a strong understanding of how our audiences were experiencing documentation and where the friction points lay:

  • Customer Feedback
    We poured through all of the customer feedback we had collected since launch.
  • User Interviews
    We reviewed all the interview notes from recent research seeking to evaluate our developer experience.
  • Workshop
    We also ran a workshop — with participants from engineering, support, marketing, data science, business development, and design — to share ideas and insights.

Opportunities

Combining all of our research, we identified a number of opportunities in the form of goals, questions, and improvements:

  • Goals

    • Enable developers to begin interacting with the API immediately.
    • Incorporate the documentation hub as a core part of the developer journey.
    • Create the most engaging developer experience in the geospatial community.
  • Questions

    • How does the platform fit into my existing workflow, product, or infrastructure?
    • Where can I find educative content and comprehensive documentation for marketplace blocks?
    • How does the documentation hub accommodate my level of expertise?
  • Improvements

    • Absence of a playground or interactivity promoting immediate experimentation and feedback with the API.
    • Information architecture needs improvement to encourage exploration and facilitate findability.
    • Messaging misaligned with a developer-focused product and visual design lacking consistency across touchpoints.

Redefining the Experience

Information Architecture

With a clear understanding of our audience and a grasp of the opportunities we wanted to address, the first step was to rethink our information architecture — how our documentation content is organized.

This exercise began with a thorough audit of all the existing content not only within the documentation website, but also scattered across other touchpoints such as our Python SDK microsite, YouTube channel, and marketing website. This content inventory would eventually form the backbone of our content strategy.

Content Inventory The content inventory that would play a key role as part of our content strategy

With a grasp of the scope of content we were working with, we began designing a sitemap centered around four pillars:

  • Getting Started
    Effectively serving as an instruction manual for the console, Getting Started covers all the fundamental features of the platform, from the catalog, to projects, workflows, and jobs.
  • Block Reference
    The Block Reference is where you’ll find documentation for all the available blocks on the platform. When you’re creating a workflow or configuring a job, this is where you’ll find specifics on input and output capabilities, supported parameters, and anything else you need to complete these tasks.
  • Developers
    The third pillar is Developers. This is where you’ll access our API reference, Python SDK, as well as supporting documentation for developing blocks and integrating with the platform.
  • Accounts & Credits
    Lastly, Accounts & Credits is where you’ll find all the administrative content from account management to pricing and compliance.

Information Architecture: Pillars The four pillars of the documentation hub sitemap: Getting Started, Block Reference, Developers, Accounts & Credits.

Content Types

To ensure our documentation best serves the needs of our audiences, we adopted three content types from Daniele Procida’s Documentation System:

  • References
    Reference documentation is information-oriented and describes specifically how features or parts of the platform work. When written well, references adopt the same structure as what they’re describing.
  • Guides
    Guides are goal-oriented and guide the reader through the steps required to solve a real use case. They tend to assume some knowledge and understanding, seeking to answer questions the reader has.
  • Tutorials
    Tutorials are learning-oriented and walk readers step-by-step towards completing a specific task. They assume the role of teaching readers and ensuring they’re able to see immediate results.

Given that references, guides, and tutorials add up to over 100 pages of content, it’s equally important that it’s well organized and easy to find.

And to strengthen what Jared Spool describes as information scent, we structured our information architecture to incorporate different types of navigation pages designed to guide readers towards the content they’re looking for:

  • Galleries
    Gallery pages are lists of links to related pages. Most navigation failures on information-rich websites are due to poorly organized gallery pages.
  • Departments
    When it’s necessary to have multiple galleries, a department page groups these galleries together. Department pages help readers narrow down a broad selection of options.
  • Home
    At the very top is the home page whose role is to identify and understand the reader when they arrive and orient them towards the department or content they’re looking for.

Information Architecture: Navigation A portion of the sitemap illustrating the navigation paths to content pages under the Getting Started department

Atomic Design

Now that we felt confident about the structure of our content, we turned our attention to how the surface of our documentation would materialize.

Adam, our UI designer, had begun exploring design directions, but given the number of navigational and content pages, we needed to move away from trying to visualize each type of page as a static template. Instead, we focused on creating a dynamic system of components that could be combined to compose the layouts we needed.

In the spirit of Atomic Design, we started looking at these design explorations through the lens of atoms, molecules, and organisms of our visual system and how they might be broken down accordingly.

Atoms

We leaned on our existing design system that had evolved from our product and marketing website and cherry picked the atoms we needed.

Atomic Design: Color Atoms We paired our existing color palette with icons to represent different areas of the product.

Atomic Design: Typography Atoms We picked out a subset of styles from our existing type system that would cover the design problems we would need to solve.

Together, this small set of design tokens (colors, icons, and typographic styles) would form the foundational building blocks for our documentation pages.

Molecules

Now that we had our building blocks, we could begin combining these abstract atoms to give them purpose.

Headings, captions, and links combined to form headers and lists. Icons, covers, and images were added to construct cards.

Atomic Design: Molecules Molecules formed simple, functional, and reusable components that we could put into a broader context.

Organisms

Bringing everything together, groups of atoms and molecules could be combined to form distinct sections of the interface.

Sections organisms served as flexible patterns that could be used to compose the gallery, department, and home pages guiding readers toward content.

Delivering on our Promise

Technology Stack

One of the core principles for this project was to remove as much friction as we could from the editorial workflow. We wanted working with the documentation to be simple and approachable, such that anyone who wanted to could contribute. And given that the editorial team were already comfortable with a Git-based workflow, we wanted them to have the option of taking further editorial control as they became familiar with the technology.

At the same time, our technology stack needed to be uncomplicated to deploy and maintain, extensible such that additional functionality could easily be enabled, and ideally maintainable by anyone on our frontend team.

Jamstack & Gatsby

With these principles in mind, Axel, our frontend engineer, proposed a Jamstack based architecture with Gatsby and MDX.

The Jamstack is a modern approach to web development based on client-side JavaScript, reusable APIs, and prebuilt Markup.

The foundation for this is Gatsby, a static site generator with a modern developer experience that’s easy to deploy and maintain by anyone on our frontend team.

And with a massive ecosystem of plugins and themes, within a day of kicking things off, Axel already had a themed boilerplate website that allowed us to begin fleshing out our information architecture and populating with content right away.

Managing content was also as easy as creating directories and Markdown files. Paired with MDX, content editors can also import components directly into content pages for further editorial control over page layouts.

DocSearch by Algolia

In the spirit of Jamstack, we looked to Algolia’s powerful API to provide our search experience. Their DocSearch program is specifically created for documentation websites and allows us to deliver a best-in-class search experience.

Their search-as-a-service takes care of the infrastructure (crawling, indexing, search engine, etc.), providing an API that makes it as simple as installing a client library, providing an API key, and readers immediately have a fast, relevant search experience right out of the box.

Content Strategy

Since we already had over 120 pages of documentation and no time to produce new content, our content strategy focused on ensuring this content had a home in the new information architecture.

Content Migration

Migrating our existing content proved to be a complex task, posing three challenges:

  • Site Map
    The new website has an entirely new information architecture so every piece of content would need to be relocated to a new home.
  • Links
    A new site map meant that every existing URL would change, requiring existing references to be updated, and redirects in place to prevent broken links.
  • Formatting
    Existing content would need to be converted from reStructuredText to Markdown whilst preserving as much formatting as possible.

Content Editing

Once we had migrated all our content into the new site map, Teodora and Seulgi, our customer support engineers, began the work of reviewing every page, meticulously editing and formatting headings, images, tables, code samples; and in a lot of cases content.

Screenshots

Another effort we embarked on was for Adam to begin updating the over 170 screenshots across our documentation, many of which had been become outdated due to changes in the product. We wanted to ensure that screenshots supported the content meaningfully without requiring frequent updates whenever the user interface was updated. This was also an opportunity to introduce some visual flair and personality into the documentation.

Catalog Search Screenshots An old and new screenshot depicting the use of filters in catalog search.

The Groundwork for a Better Developer Experience

Shortening the distance to documentation

One of the missions of our product team is to shorten the distance between intent and insight. And one of the ways we think about this is to consider the distance between the user interface and documentation.

Whether it’s measured in number of clicks, time taken, or usability; the more we can shorten this distance, the sooner our customers can uncover the insights they’re looking for.

And now that we’ve reset the foundation for our documentation, we’ve already begun exploring ways we might do this.

Ctrl+P (Quick Open)

Code editors commonly feature a ctrl+p shortcut (i.e. Visual Studio Code, Sublime Text, Vim, etc.) that allows developers to quickly search for and open files within their projects.

Now that we can search our documentation via API, what if we could adopt this convention to provide quick access to the documentation from anywhere in the product?

Quick open provides documentation search directly from the product

Embedded Documentation

A year ago, we introduced popovers within the UI to provide convenient and contextual help with deep links to the documentation for further reading.

Popovers provide an affordance for seeking help with configuring jobs

While this was a simple pattern that reduced a lot of friction and mitigated some of the usability issues, the contextual jump of a separate documentation website can be disruptive. Besides, nobody needs more open browser tabs.

So instead of directing readers to the documentation, why to bring the documentation right within the context it’s needed in the form of an embedded browser?

Browsing the jobs and API reference with embedded documentation.

What excites us about this approach is that you’re able to reference both the user interface and documentation side by side whilst completing tasks without having to switch back and forth between browser tabs.

And to take it one step further, we could also surface the API reference to illustrate how you would accomplish the same task with our API.

What’s next?

This is just a peek at some of the directions we’ve been exploring, but if you’d like to receive invitations for early access to new features, join our Early Access Group.

In the meantime, check out our new Documentation Hub — we’d love to hear your thoughts and ideas.

John Ngo

UX Designer at UP42

Start building with UP42

Ready to get started? Create an account in seconds and we'll even give you 10,000 credits to get your first insights.

Get started