The challenge

In 2022, Finboot embarked on an ambitious project to provide developer documentation for MARCO, their agnostic blockchain platform. As a pioneering blockchain platform, MARCO offered immense potential for developers. However, its capabilities and complexities necessitated detailed documentation to ensure users could effectively implement and innovate upon it.

We worked with Finboot to design a documentation strategy, choosing the tools for the site, writing and editing content, and sharing best practices with the development team to streamline future maintenance of the documentation.

Crafting a strategy

Understanding the importance of documentation, Finboot and our team came together to define a documentation strategy. This strategy aimed to address several critical goals:

• Accessibility: Ensuring information was easy to find and understand by developers of varying skill levels.
• Completeness: Covering all facets of the MARCO platform, from basic setup to advanced functionalities.
• Maintenance: Facilitating easy updates to documentation alongside the platform's evolution.

Integral to this strategy was the delineation of target audiences, the identification of products, the establishment of a comprehensive documentation catalog, and the creation of a roadmap to guide the development and maintenance of the documentation resources.

Selecting the tools

In choosing the right tools for our documentation, ease of contribution and maintenance was a top priority. We opted for Docusaurus, primarily because the developers were already familiar with editing Markdown documents, which made it easier for them to contribute. This choice allowed the documentation to be closely integrated with the code, facilitating updates and contributions.

Additionally, Docusaurus offers visually appealing template that required minimal effort to set up. Its wide range of plugins also made it easy to integrate with version control systems and continuous integration workflows, streamlining the documentation process.

Content creation and editing

After selecting our documentation tools and establishing a plan, we began to create and refine the content.

By adhering to structured, topic-based authoring principles, we were able to produce initial drafts efficiently. These drafts underwent a detailed review process to ensure they were accurate and consistent.

To streamline our documentation efforts, we implemented processes to automatically generate parts of the documentation directly from the code, like the OpenAPI specifications.

Empowering the development team

Crucial to our approach was involving Finboot's development team in the documentation process, empowering them to both contribute to and maintain the documentation. We facilitated this by sharing templates and a style guide to ensure consistency and high quality throughout.

Additionally, by keeping the documentation alongside the code, we made it simpler for developers to make updates concurrently with their development tasks. This setup encourages a collaborative culture, with the development team actively participating in the contribution and review process, ensuring the documentation remained accurate, relevant, and comprehensive.

The launch

The launch of the MARCO documentation site marked the successful culmination of our efforts. Our methodical approach to content creation, alongside empowering Finboot's development team to contribute, provided a robust foundation for the documentation to expand and adapt with MARCO's ongoing development.

This successful implementation has established a model for Finboot's future documentation projects, showcasing the impact of a strategic and well-implemented documentation approach on maximizing the utility of complex technological platforms.

Tech stack