The client
NEM is a community-driven blockchain platform for building decentralized applications launched in 2015. The NEM Foundation is a non-profit organization that promotes the adoption of blockchain technology and supports the NEM ecosystem.
The challenge
In 2018, NEM Foundation started promoting Symbol, the next version of NEM targeted at enterprise use cases, by offering in-person workshops to system integrators and university students. However, they realized this approach would not scale well without documentation since the questions from trainees were repetitive, and the answers were not always accessible.
Additionally, if a company or individual developer who had not attended a workshop wanted to use the technology, there were not enough resources to onboard them other than the source code itself and some first guides written by the community in personal blogs and forums.
The solution
For two years, I've 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.
Symbol's Developer Portal
Information architecture
Before even considering creating a developer portal, we collected all the available docs from the forums and blog posts. Then, we classified them between explanations and procedures. Later on, we started adopting the Diátaxis framework, which expands this division into four different categories: tutorials, how-to guides, explanations, and references.
Diátaxis framework diagram
Organizing the docs depending on the type of content has its benefits. For example, where to add new documentation became a no-brainer since we only had to consider the type of document. Besides, it helped us not to mix different documentation types in the same document.
Tutorials
Tutorials are lessons that take the reader by the hand through a series of steps to complete a project. All tutorials we write for the Symbol Documentation focus on architecting solutions by combining a set of features. Every lesson starts presenting a short use case and the list of materials necessary the reader should complete before moving to the hands-on.
Sample tutorial
Writing your first application is the first tutorial readers take after setting up their development environment. Additionally, we documented the workshops NEM Foundation was delivering and made them available from the developer portal. By doing so, every workshop was repeatable, and anybody could access them after the training session.
How-to guides
How-to guides are like recipes that take the reader through the steps required to complete a task. In blockchain's context, this could mean issuing a transaction, creating an account, or deploying a custom network.
Guides for managing multisig accounts
Since the target audience of the docs is developers, every guide can be resolved with the Desktop Wallet (graphical interface) or using Symbol's SDK with code snippets in three different programming languages:
Sample code snippet
Explanations
Explanations don't guide the reader on what to do but introduce what they could achieve with Symbol.
Sample explanation document
We classified almost all explanations are under the modules Built-in features and Protocol. The first module presents each transaction type's constraints and uses cases, whereas the second explains how the blockchain works internally.
References
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. In addition, other reference docs that are prone to change are generated automatically directly from the code. For example, we build a custom pipeline to autogenerate the Symbol CLI reference documentation in order to keep the docs always current without spending time on manual updates.
Content creation and revision
After organizing and curating the existing documentation, we listed the missing documentation based on the questions trainees and the community had. Then, release after release, I coordinated with the development team to know which features they would introduce next and ensure they were covered in the documentation.
With the help of the team, we progressively created the missing how-to guides, technical references, and explanations.
Symbol documentation
Since Symbol is a community-driven project, the requirements and new features could come from different sources. To keep track of them and create discussions around the proposals, we launched the NEM Improvement Proposal process for submitting improvements to NEM & Symbol.
NEM Improvement Proposal repository
Usability improvements
As the lead technical writer, I was 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. This delay could be frustrating for developers who want to try the new features as soon as possible.
For this reason, I implemented new features in the Symbol CLI, a collection of scripts to interact directly with the REST API from the command line prompt.
Symbol command line interface
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.
API Design First
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.
Portal development
Symbol docs consumers and contributors are mainly developers. Thus, the documentation CMS should adapt to the developers' way of working to be a success. Therefore, instead of using a full-featured publishing platform, we wrote all the docs in plain text with Sphinx near the code.
We implemented Docs as Code workflow to automate the revision and publication process using the GitHub issue tracker and Travis CI.
Additionally, we developed a custom theme with Algolia DocSeach integration to provide the best search experience across the complete documentation site.
Docs search with Algolia
Symbol's fantastic community actively localized the contents of the developer portal into Japanese. For this reason, we installed Transifex, a collaborative localization platform, to manage translations and make the localization process participative.
Symbol Documentation translated into Japanese