Introduction

Reason is a truly open platform, with hundreds of contributors putting in tremendous Open Source effort to make the language better every day. There has been a lot of distributed involvement to provide learning materials for newcomers and to improve documentation such as APIs, libraries and language features. These things are necessary to stay productive while using the language.

Also due to its flexible nature, it can be used for many different use-cases, most prominently for JavaScript based web development (Frontend / NodeJS via BuckleScript), for natively compiled OCaml projects (via the OCaml platform), and recently as an alternative syntax for Tezos’ smart contracts.

Even though there has been significant involvement in building new features for the Reason platform, knowledge and advice on common practise has been scattered around the web, leaving the official documentation scarce in comparison to what already has been successfully built with the language already. Most of the knowledge does exist, so what we need is a new concept of bringing it all back together.

Background & Challenges

The Reason ecosystem is currently split across multiple projects and websites, such as:

• Reason (Language Reference: https://reasonml.github.io/)

• Reason Playground / Try section (https://reasonml.github.io/try)

• BuckleScript (OCaml based compiler for compiling to JavaScript: https://bucklescript.github.io/)

• OCaml Stdlib (https://reasonml.github.io/api/index)

• BuckleScript’s OCaml Stdlib (https://bucklescript.github.io/bucklescript/api/Js.html)

• BuckleScript’s Belt Stdlib (https://bucklescript.github.io/bucklescript/api/Belt.html)

• The Esy Package manager for native development workflows (https://esy.sh/)

• Redex Package Index (https://redex.github.io/)

• GenType - A meta tool for automatically creating JS / TypeScript / Flow bindings for Reason code / ReasonReact components (https://github.com/cristianoc/genType)

• Sketch.sh - A platform for runnable & sharable OCaml / Reason snippets (https://sketch.sh/)

Even though most knowledge is openly accessible, it's not always clear what kind of information is up to date, or relevant for the task at hand. The Reason and BuckleScript docs are coupled in certain instances, but don't offer enough concrete information on how to get a Reason / BuckleScript going in a real world setting.

Users are left alone with important decisions, such as what CSS solutions to use within ReasonReact, how to handle JSON (de)serialization / Promises properly, or how to apply well-known ReactJS concepts in ReasonReact.

The Vision

Over the last one-and-a-half years, we and many other community members spent a lot of time thinking about how to teach the language in the best way possible, so that newcomers can get productive very quickly while experienced users can enjoy a very well designed documentation system.

Akin to the latest efforts in the OCaml community, we want to have a unified experience for all of these concepts. The idea is to think about proper user journeys for different backgrounds, and organize the documentation in a way that makes sense in the right context. 

For the future vision, we want to be able to cover following user-journeys:

1. Reason / OCaml web development with BuckleScript

2. Reason / OCaml native development (esy, dune, JSOO)


3. Other relevant stories (React-Native, Tezos smart contracts)

Example: as a web developer (1), the user shouldn't be exposed to OCaml Stdlib APIs which are not available in BuckleScript, vice versa as a native OCaml developer (2), the user should not be forced to skim through unnecessary web related content such as BuckleScript externals or uncurried functions.

Our vision is to have a unified reasonml.org website¹, with first class curated content and a superb onboarding experience, with nice UX and UI to make it pleasant to look at and work with.

To make this happen, we will act in multiple phases / sprints to set specific feature scopes. In all our development tasks, we will involve our UI / UX designer to visualize UX goals with strong human-centered-design principles.

During the whole development process we also want to provide an open continous delivery pipeline to enable the community to give feedback and contribute changes.

Phase 1

The first phase will be our short discovery phase, where we try to gain an overview over the whole platform. Even if we are not working on all parts of the documentation right off the bat, we want to make sure we build each part in a way so they are consistent with the rest of the platform.

Tasks:

• Prioritize, order and update existing knowledge (starting with the official Reason, ReasonReact & BuckleScript docs)

• Gather feedback for docs improvement from the community (find missing pieces of information)

• Get a high level overview on how users interact with the documentation

• Evaluate the right tech to achieve the desired UX

• Give our designer a high level overview over the system

• Define a process and Code of Conduct for external contributions from the community (PRs, etc.)

Phase 2

We will start with the web development user-journey, which means we will start working on the BuckleScript documentation and push out first prototypes of a reimagined BuckleScript website. Tasks for this phase will include:

Belt API docs

• Extracting all Belt usage examples into markdown format, also making the examples more accessible for non-OCamlers.

• Using the markdown information for building a custom Belt API website³, with useful features such as a search interface for finding equivalent Belt functions when entering a specific JS function name (e.g. [].map -> Belt.List.map),

BuckleScript docs

• Apply UI learnings from the new Belt API docs to the BuckleScript website

• Apply a JS developer mindset to the documentation structure, simplify content and give more high-level views over specific patterns

• Build a feature which allows us to have a one click feedback button on each doc page

• Improve the current try playground / collaborate with sketch.sh to be able to run interactive Reason / BuckleScript snippets

Odoc

• Apply our learnings from extracting the Belt docs from the BuckleScript source code to be able to improve the odoc tool.

• Fix long pending issues with the Reason syntax generation and enable the Reason / OCaml toggle feature

• See the doc-tools project for more concrete details

Phase 3

Upcoming phases are not scope of this article yet, but will be defined in future updates where we will also report on our progress and learnings.

Funding

We want to thank our donors to fund our initial effort. To make our project more sustainable, we are seeking out additional donations from organizations and individuals. If you are interested in donating, please get in touch or refer to our donations page for instructions.

Collaboration

We want to provide the best possible learning experience for the ReasonML platform, with great UX, tools and nicely written docs. This endeavour aims to be a community project, so we highly appreciate and encourage individual contributions, no matter what kind and size (docs, code, UI, tools, READMEs,...).

We are also looking for OSS contractors to be an integral part of the project team, especially for following areas:

• Technical Writing

• Interactive Coding Environments (Backend / Frontend driven)

• Accessibility for (Reason)React applications

If you are interested and want to take part, please let us know.

Follow our work on Twitter and Discord and stay tuned for future updates.