# Docs on OCaml.org

*Attending: Jon Ludlam, Gemma Gordon, Bella Leandersson and Patrick Ferris (Thursday 11th March 2021)*

## Current Situation

Currently on OCaml.org there are two sections linked from the main navigation bar that relate to our problem: [learn](ocaml.org/learns) and [docs](ocaml.org/docs). It's a little bit of a mess, for example:

- Within in *Learn* we also have industrial users and success stories, but *Learn* is probably more geared towards people wanting to learn the OCaml language.
- *Docs* is essentially a wrapper around the manual pointing to various interesting bits and also some books and a brief description about opam.

For any new user coming to OCaml.org the narrative is confusing and (as we've discovered) a lot of these words are overloaded. We plan to fix this is the new ocaml.org site.

## A new hope

Everything is subject to change, but the current plan is to pull both of those sections under a *resources* section. In addition to this we want to remove the ambiguity that words like *learn* have (learn what? libraries, tools, the history of OCaml?!). We propose two sections.

### Language

The language section is solely concerned with providing context to different sources of learning about OCaml including:

1. Beginner tutorials (OFronds eventually)
2. Books (RWO, OFTB etc.)
3. Manual -- similar to what's currently on ocaml.org/docs
4. Applications (more on that later)
5. Papers

The ordering here is intentional. It is supposed to reflect a beginner to advanced OCaml user and the different resources they might need along that journey. A preliminary design of such a page is:


The applications section links to our second area under resources.

### Applications

This is perhaps the harder section to pin down. Our goal is to provide a collection of resources that cater to our archetypes:

- Library Authors
- Application Developers
- End Users
- Distribution Managers
- Teachers

I've removed *beginners* because I feel like they start with the language page. The information that this encompasses is:

- API Documentation (the main/original goal of docs.ocaml.org)
- Developer Guides: I don't think we have a good definition for what this is but the closest thing to it in my mind is either dbuenzli [style API docs](https://erratique.ch/software/brr/doc/index.html) or [ocsigen style docs](https://ocsigen.org/js_of_ocaml/latest/manual/overview). The work Craig has been doing with Mirage is directly linked to this I think.
- Using OCaml: information about using tools built in OCaml such as Coq.

One section that is missed here is workflows and information about the Platform tools (dune, opam, ocamlformat...). I don't think we quite know where this belongs just yet or how they fit into the overall picture. Manuals are not enough, they act as a good reference for users who need to deep-dive into something they already know about but are not of much use to someone who wants to use them in a project.

A preliminary layout for this page is:


# Questions

The main question is what are everyone's thoughts on this structure? Are we missing something? Is there a better way to present this information.

Here's a list of open questions in no particular order:

- What is docs.ocaml.org now? From what I can gather it started as a complicated rendering oflibrary APIs but is it also now package search (a.k.a. opam.ocaml.org/packages 2.0)?
- Tooling for writing developer guides and where do these live? Will odoc be the tool to do this so library dev guides and API docs live together?
- Platform Workflows, where does these live, are they just another form of developer guide?
- Platform tool information, in the resources/application section?
- What story do we want to tell on the resources/application page? It is not immediately apparent to me how we help users find the information they need.