Symbol is a next-generation, open-source decentralized blockchain platform from NEM that connects businesses to blockchain and helps them to reduce cost and complexity – making Symbol the smart, pragmatic choice for both enterprise and developers.

The starting point

In 2016, NEM expanded globally, and the core developers started to work on Symbol, reimagining from scratch the ideal blockchain and improving on NEM’s V1 performance and feature set. To promote the product between developers and system integrators, NEM Foundation was looking for a professional with technical and product experience to spearhead the new product documentation efforts from scratch.

The objective

On the one hand, I had to create and curate content for Symbol developer audiences. The open-source software was under active development, and most of the information available was the code itself, and design documents shared between the core developers.

On the other, it was necessary to unify all the documentation resources under a single platform to share it with developers, system administrators, and decision-makers looking to integrate Symbol into their project.

The final result

Over the space of two years, I owned the product documentation roadmap while the project was under active development and authored many of the how-to guides, technical references, explanations to onboard developers, system integrators, and internal employees.

After working intensively with the development team, marketing, and the community members, we launched docs.symbolplatform.com, the developer portal containing all the necessary information to start integrating blockchain technology into your project.

Information architecture

At the start of the project, we collected all the available docs from the forums and blog posts. Then, these contents were divided into four categories following Divio's documentation system: tutorials, how-to guides, explanations, and references.

Divio Documentation System

Divio's Documentation System Diagram

Tutorials

Tutorials are lessons that take the reader by the hand through a series of steps to complete a project. All tutorials in the Symbol Documentation are focused on architecting solutions by combining a set of features. Every lesson starts preseting a short use case, and the list of materials necessary the reader should complete before moving to the hands-on.

Writing your first application is the first tutorial the user reads in the documentation takes after setting up their development environment. In the future, tutorials will be progressively moved to the sibling project Symbol Academy, a second portal that will offer free Symbol official training.

How-to guides

How-to guides are like recipes that take the reader through the steps required to complete a task. In the blockchain world, this means issuing a transaction, creating an account, or deploying a custom network.

Guides for managing multisig accounts

Guides for managing multisig accounts

Each concept includes links to related guides on how to use the feature. Every guide can be solved with the Desktop Wallet or using the SDK with code snippets in three different programming languages: TypeScript, Javascript, Java, and Bash.

At the early stages of development, there was no graphical view to interact with the network. Since only the REST API was available, we developed the Symbol CLI. The tool is designed to help developers architect solutions and interact with Symbol networks from the command line prompt.

Explanations

Explanations provide the bigger picture, the context. They don't guide the reader on what to do but introduce what they could achieve with Symbol.

Almost all explanations are under the sections Built-in features and Protocol. The first section presents each transaction type's constraints and uses cases, whereas the second explains in-depth how the blockchain works internally.

Reference

The reference documentation describes details about the available tools and programming elements associated with those technologies, including the REST API Reference or SDK autogenerated documentation.

Symbol OpenAPIs Specification

Symbol OpenAPI Specification

The REST API Reference is published automatically from the latest OpenAPI Specification. Moving the contract to a separate repository helped the project follow an API Desing First approach. Before, the implementation mostly guided the contract. Now, the contributors from different projects consuming the API collaboratively propose improvements and discuss new endpoints before the team implements them.

Portal Development

Symbol docs consumers and contributors are mainly developers. Thus, we believe that the documentation system to be a success should adapt to the developers' way of working.

All docs are written in plain text using RestructuredText. This allowed us to implement a docs-as-code workflow to automate the revision and publication process using the GitHub issue tracker and Travis CI.

We choose Sphinx documentation system to create the developer portal with a custom theme. Sphinx was conceived to document Python software projects, but it quickly evolved to a more generic tool to develop and maintain technical documentation, developer portals, and even books. The site integrates Algolia DocSeach to provide the best search experience across the complete documentation site.

Algolia DocSearch

Docs search with Algolia

Other docs that are prone to change are generated automatically directly from the code. For example, we built a tool to autogenerate the Symbol CLI reference aiming to keep the docs accurate without spending so much time maintaining them release after release.

Internationalization

Symbol Documentation Japanese

Symbol Documentation translated into Japanese

Symbol's fantastic community actively localizes the contents of the site into Japanese. The documentation site uses Transifex, a collaborative localization platform, to manage translations and make the localization process participative.

NEM's opinion