In the past few months, the Velo by Wix team upgraded our large-scale open-source documentation and code completion system. It allows hundreds of developers and tech writers to embed their documentation and autocomplete hints next to their source code while keeping the generated documentation portal stable and low-maintenance.
If you’re writing a complex software platform that consumes multiple components from various sources, we hope that the below read is helpful.
Photo by Arthead on Adobe Stock
What is Velo?
Wix is a cloud-based development platform. Velo is a serverless JavaScript open platform that lets developers add frontend and backend code (along with databases and other tools) to any Wix site. Simply put, a user writes code to build their web application while Wix automagically handles things like security, resource management, scaling, monitoring, etc.
The purpose of documentation and code completion
Exploring a new software service can be challenging. Accurate documentation is the map that helps you explore a new world, while powerful code completion is like a compass that guides developers in the right direction as they go. Without documentation, nobody would find and choose a particular solution. Without autocomplete, using it would be tedious and cumbersome.
Autocomplete helps developers understand the mental model of the project, explore the software APIs, and boost productivity by reducing the need to memorize function names while elevating code stability. It increases user engagement by guiding users to the correct usage, decreases code breakability with validation, and helps avoid typos or other mistakes.
The challenge with hundreds of APIs
Velo offers hundreds of in-house software components and services to its users.
Our users expect updated documentation synchronized with an in-browser and offline completion service. It’s straightforward when there’s a single API; but how do we do it with hundreds of them?
Those packages are written in JavaScript and TypeScript by Wix developers from all across the company. Our tech writers describe their package APIs using JSDoc annotations that live inside the source code:
We managed to find an elegant solution to this challenge, providing both flexibility and stability. It seamlessly combines documentation and code completion definitions from multiple sources into a single platform.
Our Solution
We decided to use the TypeScript compiler as the code analysis engine, which means that all our APIs should be declared in typings files (.d.ts). We generate those definitions from the JSDoc annotations on every change in our packages.
To update the completion and documentation model, our tech writers perform a CLI command at the relevant Git repo that pushes their changes to a branch at a centralized docs repo. The docs repo holds custom JSON models that are generated based on all the JSDoc annotations from the different parts of Wix.
Then a tech writer runs tests on the new target model that make sure all components and Wix APIs work as expected. After automation tests pass, the new docs model can be merged. It will trigger an automated process that converts the custom JSON model to Velo API referenced site and static d.ts files.
Now that we have the d.ts files we need to provide the IDE with the right d.ts according to their working context. For example, when a user writes a code file that runs in the backend, we serve the definitions of the wix-backend APIs and NodeJS modules. A code file that runs in the frontend requires the definitions of wix-frontend APIs. We also generate dynamic definitions at runtime that describe the current state of the site - like elements available on a specific page, database collections structure, installed npm packages, and more.
After we calculate the user context and the relevant .d.ts files that are required in that context, we provide these files into our online IDE. We use the Monaco editor with its typescript plugin, but .d.ts support is pretty much universal.
For instance, we built a CLI tool that enables our users to download and edit their code with their favorite IDE - like VSCode, IntelliJ, etc. We serve the same definitions described to the IDE and our users get an identical TypeScript based autocomplete experience.
Takeaways
TypeScript definitions (.d.ts) are the industry standard definitions of the language. They’re extremely flexible, and provide out-of-the-box support for almost any online or offline editor even for the most complicated APIs in our system.
Using a compilation process to test a new documentation and completion model prevents breakage and inconsistencies due to mistakes in the origin files generated by the tech writers.
Generating the documentation and autocompletion definitions from the same source of truth minimizes doc/IDE discrepancies. There are numerous .d.ts to docs conversion tools out there for those who want to store the source of truth in the .d.ts files instead of JSDocs.
Want to try it out? Click here.
This post was written by Kobi Nemni
For more engineering updates and insights:
Join our Telegram channel
Visit us on GitHub
Subscribe to our YouTube channel