When I complete a project, I like to reflect on what we did, what worked well, and what we could have done better. In this article, I'd like to share the process we followed to release docs.symbolplatform.com - a developer portal containing all the necessary information to start integrating Symbol into your next project.
The challenge
In 2018, I joined the NEM Foundation to create content for developers for Symbol, a new open-source and decentralized blockchain platform built on the learnings of NEM.
At that time, NEM Foundation was promoting the technology by offering in-person workshops to system integrators and university students. Quickly, we realized that this approach was not scaling well without documentation: trainees were always asking the same questions, and we had to act as consultants of the product to resolve them.
Additionally, if someone who had not attended a workshop wanted to use the technology, they had little information available other than the code itself, design documents shared between core developers and a few posts and guides written by the community in personal blogs and forums.
For two years, I've worked with the development team, marketing, and the community members to launch and maintain docs.symbolplatform.com - the developer portal containing all the necessary information to start integrating blockchain technology into your next project.
Information architecture
Before even start thinking of creating a developer portal, we collected all the available docs from the forums and blog posts. Then, we classified them into four categories following the Diátaxis framework: tutorials, how-to guides, explanations, and references.
Diátaxis framework diagram
Agreeing on a standard way to organize the documentation has its benefits. For example, where to add new documentation becomes 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.
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 docs are developer-oriented, we decided that every guide can be resolved with the Desktop Wallet (graphical interface) or the SDK with code snippets in three different programming languages: TypeScript, Javascript, and Java.
Looking back, mixing the desktop wallet and developer documentation has reduced the number of documentation pages, and there is much less content duplication to maintain. However, it became more challenging to define user-defined flows for non-technical audiences. For example, node operators or investors are not interested in code snippets, but they see them indirectly when they access the wallet-related docs.
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.
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. 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 to keep the docs current without spending so much time maintaining them release after release.
Content creation and revision
After organizing and curating the existing documentation, I've 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 make sure 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 some discussions around the proposals, we created 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 since a feature is released at the network level, and the same feature is usable from the graphical interface.
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 me and the community 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. Instead of using a full-featured publishing platform, we decided to write all the docs in plain text with Sphinx near the code.
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.
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