The challenge

Weave.js is a free, open-source framework created by Inditex (the company behind Zara) for building real-time collaborative whiteboard applications, like shared canvases and diagram editors, on HTML5 Canvas.

The framework had been battle-tested in production before going open source, but it was new to the open-source world. As the team's own disclaimer put it, the documentation needed "more battle testing" before they were happy with the developer experience.

That gap mattered most at the very start of the journey. A developer's first encounter with Weave.js is the quickstart and the manual installation guides. If those guides assume internal context, skip dependencies, or contain copy-paste errors, an outside developer hits a wall before they ever see the framework work, and most of them never come back.

The review

We went through the getting started experience the way a new developer would: following every step literally, on a clean machine, with no internal knowledge. Three things stood out.

• The install didn't work outside the company's internal setup. A developer following the guide hit dead ends before the framework ever ran.
• The overview was a single long page. It mixed concept, architecture, and reference, so newcomers had nowhere clear to start.
• The setup guides jumped straight into commands. No prerequisites, and no way to tell whether a step had worked.

What we did

We worked through these issues and contributed the fixes directly to the repository, through a series of merged pull requests.

Restructured the overview. We split the monolithic overview into focused, navigable pages — a clear Architecture page, an Application structure page covering the frontend and backend artifacts, and a Glossary. The result explains how the pieces fit together (canvas rendering, real-time sync, the plugin and actions system) instead of burying it all in one wall of text.

Rewrote the setup tutorials. We reworked all the getting started guides into a consistent shape: each one opens with prerequisites, runs through an explicit step-by-step sequence, and ends with a verification step so developers know they're on track before moving on.

Made the install reproducible. We fixed the steps that only worked in the company's internal setup so a developer anywhere can install dependencies and reach a running app by following the guide as written, and added a pointer to the reference sample project for those who'd rather skip ahead.

Single-sourced the code samples. The original snippets were pasted inline and, in places, didn't even compile — the root cause of the docs drifting from the real code. We moved them to pull directly from a working project, so the docs show exactly what runs and stay correct as the team verifies that project on each release.

Proposed leaning into visuals. Weave.js is a visual tool, so we recommended showing what each step produces with screenshots and illustrating concepts in the reference material, and refreshed the existing screenshots and GIFs to match the current UI.

The outcome

The getting started path now works end to end for a developer with no prior context. The restructure made the docs readable and predictable, the rewritten tutorials give a clear path from zero to a running app, and the install actually completes by following the steps as written.

For an open-source project earning adoption beyond the company that built it, the first ten minutes of documentation are the product. This work made those ten minutes deliverable.

Tech stack