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.
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.
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's Documentation System Diagram
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 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
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 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.
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 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.
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.
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.
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.