Looking for Participants for User Survey on ocaml.org Package Documentation and Learn Area

Community
,
36

Here’s the promised update on what kind of feedback we got out of the user survey. I tried to distill as best as I could, there was so much feedback! :slight_smile:

We have responses from 20 people in total, and a lot of those have volunteered to be interviewed by Claire. So this is excellent! In the interest of getting a good overview of the userbase, Claire will select people and send out invites.

Summary:

17 people are using OCaml for personal projects, 7 for business purposes, and 6 use OCaml for research purposes.

We have a good mix of junior and senior software development and research roles, as well as organisations of varying sizes and a broad mix of tasks people work on. I do not list these individually.

Pain points / package documentation:

Ideas/suggestions package documentation:

  • Tree navigation should be improved, e.g. library vs toplevel module should be consolidated, hiding other libraries when going down into a module should be removed
  • Index for declarations (values, types, exceptions, etc.) of a module could be displayed in place of the empty TOC / appended to the TOC

Problems with content and documentation writing experience:

  • Lack of example code, quality of documentation on package docs displayed on ocaml.org
  • UI/UX of odoc for writing package documentation could be improved
  • hard to incorporate ocamldoc and markdown when writing documentation

Workarounds / package documentation:

  • inspect source code
  • odig, sherlocode.com, opam grep
  • look at package’s tests
  • search in forums, StackOverflow, look for links to package author’s documentation site in package’s public git repository

Pain points / learning section:

  • Layout/scroll problems on https://ocaml.org/doc. People need to scroll too much to see the content. Scrolling down the page does not show the tutorials and guides section, scrolling down the navbar on the left it is hard to scroll down to “common error messages”, “best practices” and “OCaml platform” (Too much scrolling required on the "Learn" page · Issue #850 · ocaml/ocaml.org · GitHub)
  • Accessibility problems w/visual contrast (Add Accessibility-Checking to the Continuous Integration · Issue #835 · ocaml/ocaml.org · GitHub)
  • Difficulty level/prerequisites of tutorials not always clear
  • Lack of important content (e.g. “single-page syntax introduction”, dune and opam guide, task-oriented examples for different levels of language learning)
  • Styling difference between manual/stdlib API and main pages
  • “Standard Library API” link goes to the index instead of to Chapter 28 of the OCaml manual (manual gives a more adequate introduction to the standard library for beginners and does not expose internal functions like the automatically generated index does)
  • Problems with outdated information

Pain points overall:

  • Site doesn’t motivate people enough to use OCaml by showing how OCaml is cool, interesting, nice to use and how using it makes you a better programmer

Ideas/suggestions learning section:

  • The more basic sections, e.g. if statements, pointers, could be merged or made collapsible to make it easier to see all items on the side navigation
  • “Papers” section is not so relevant to most OCaml beginners and should be moved below “Books”
  • Have a “beginner”/“advanced” toggle at the top of the learn page that switches the content area to be tailored better to the different use cases
  • add more context on who should read a particular book (e.g. prerequisites, topics covered)

Workarounds learning section:

  • directly go to the manual
  • books, blogs, other sites
  • ask on forum/discord/StackOverflow
  • check ocamlverse

Tbh, this took a bit longer than I thought: there is so much useful info in your feedback! I want to add links to corresponding issues, but this will have to wait until I edit this post tomorrow.

10 Likes