The challenge

Back in 2018, the NEM Foundation started promoting Symbol, an advanced version of NEM designed for enterprise applications, through live workshops aimed at system integrators and university students. It quickly became evident that this method wouldn't scale effectively without comprehensive documentation. The same questions were being asked repeatedly in these sessions, and consistent, accessible answers were lacking.

Moreover, for any company or individual developer who hadn't participated in a workshop, the options for getting up to speed with the technology were limited. Beyond the source code and a handful of initial guides scattered across personal blogs and forums by the community, there were few resources available for new users to familiarize themselves with Symbol.

We worked closely with the development team, marketing, and community members to launch and maintain docs.symbolplatform.com - a portal for developers containing all the necessary information build solutions on Symbol's blockchain platform.

Information architecture

Before diving into the creation of a developer portal, our first step was to gather all existing documentation scattered across forums and blog posts. This initial collection was organized into two main categories: explanations and procedures. This categorization laid the groundwork for a more sophisticated structure, leading us to adopt the Diátaxis Framework. The Diátaxis Framework further divides content into four distinct categories: tutorials, how-to guides, explanations, and references.

This structured approach to organizing documentation by content type offered several advantages. For instance, deciding where to place new documentation became straightforward, as it simply involved identifying the document's type. Additionally, this method prevented the mixing of different types of documentation within the same document, ensuring clarity and coherence across the portal.

Content creation and revision

After organizing the pre-existing documentation, we identified gaps based on recurring questions from trainees and community feedback. With each new release, we worked closely with the development team to anticipate upcoming features, ensuring they were documented in time for release.

Together with the team, we systematically filled in the missing pieces, creating essential how-to guides, technical references, and explanatory content.

Bridging development and documentation

We where one of the first users to test the new features to document them. However, it could span months between when a feature was released at the protocol level and when it was available in the graphical interface.

For this reason, we implemented new features in the Symbol CLI, a collection of scripts to interact directly with the REST API from the command line prompt.

This allowed us to test features while under development and share possible usability improvements with the development teams before the release.

In addition, we moved the API contract to a separate repository to adopt an API Desing First approach:

Before, the implementation mostly guided the contract. Now, contributors from different projects consuming the API collaboratively propose improvements and discuss new endpoints before implementing them.

Documentation portal

Given that Symbol's documentation would primarily serve developers, we tailored our content management system (CMS) to align with their workflows. Rather than opting for a comprehensive publishing platform, we chose to write all documentation in plain text using Sphinx, keeping it close to the codebase.

We embraced a Docs as Code approach, automating the revision and publication process through the integration of GitHub's issue tracker and Travis CI for continuous integration and deployment.

To enhance the user experience, we developed a custom theme integrated with Algolia DocSearch, ensuring a superior search experience throughout the documentation site.

Recognizing the value of Symbol's vibrant community, we witnessed the enthusiastic localization of the developer portal into Japanese. To support and streamline these efforts, we implemented Transifex, a collaborative localization platform.

This tool not only facilitated translations but also made the localization process more interactive and community-driven.

Tech stack