Stream: contributing

Topic: Docathon?

Aurélien Geron (Oct 13 2026 at 00:01):

Now that the language seems pretty stable, it might be time to organize a docathon to update all the docs? Perhaps a few volunteers can prepare a list of docs to update/write and provide some general instructions, then anyone can contribute over a weekend or a week?

Luke Boswell (Oct 13 2026 at 00:17):

Is the langref link to the website broken? the langref is complete, but the website says it is heavily WIP and there is a lot missing i.e

website

repository

Luke Boswell (Oct 13 2026 at 00:18):

Other than the Tutorial which Richard has said he wants to write ... what other docs need updating?

Aurélien Geron (Oct 13 2026 at 04:31):

Yeah, it's this sentence "This is heavily WIP!" that made me think we need to complete/update the docs before 0.1.0. If the langref is already done, great! :grinning_face_with_smiling_eyes:

I ran into a number of outdated statements here and there, such as saying that an if must always have an else, even though this is no longer true since we have return now.

The playground is also outdated, I'm not sure why (I thought we had fixed that).

The examples page feels disorganized. It should perhaps be organized by categories, and/or examples should perhaps have tags about their main concepts or main API.

Things feel a bit disjointed: perhaps the langref and standard lib docs should point to examples, and vice versa.

Also, several things are not covered by examples, if I'm not mistaken:

• Iterators and ranges
• for, while, and var versus fold
• Nominal versus opaque types
• Polymorphism and where constraints
• Closures
• Custom equality and hashing
• Sets

Moreover, having some examples of common packages and platforms would be good, such as unicode (in more depth), path, roc-ray, etc. Alternatively we could just point to these packages, but right now we have examples for basic-cli, basic-webserver, http, roc-ascii, roc-parser, and roc-random, so I think it would make sense. The platform and package examples should each be in their own section in the examples page.

Perhaps a "Tips and tricks" or "Best practices" page would be useful, and a docathon would help figure out what to recommend. For example I like to use Try(Foo, _) during dev and be more specific only at the end, switching to Try(Foo, [A, B, C]).

There's certainly more to do. Completing this To-Do list is what I suggested for step 1. Perhaps there's not enough work to justify step 2, but in many projects I've worked on, the docs weren't get enough love, and I've found that a short focused effort is a good solution to solve that.

Luke Boswell (Oct 13 2026 at 04:45):

Richard Feldman said:

The focus from there would be fixing bugs without regressing other things, which I'd like to do by getting a corpus of projects that work on RC1, and having CI tell us when we have broken them in a nightly release.

The broader examples might tie in nicely with the new requirement we have for testing things outside the repository -- the failing examples would tell us when we have broken things downstream, but also not block PRs.

Luke Boswell (Oct 13 2026 at 04:48):

I've been setting up my CI workflows so I can know when a nightly breaks something (either I need to patch the platform and make a new release, or report a bug back upstream).

Aurélien Geron (Oct 13 2026 at 04:50):

I'm happy to submit a few new examples. Btw, several examples are in the examples repo but not online (e.g., custom literals, hello web, webapps with Elm, sorting strings, multiline-comments)

Luke Boswell (Oct 13 2026 at 04:57):

The website and CI supporting that definitely need some love :smile:

Aurélien Geron (Oct 13 2026 at 05:05):

The benefits of a docathon go beyond simply improving the docs: it can be a fun community-building activity, an opportunity to discover & discuss other issues, and a way to get people to care more about docs if they've contributed to them.

Aurélien Geron (Oct 13 2026 at 05:21):

Apparently the reason why the website is still using an old playground and is missing several examples is that the latest Cloudflare production build failed. I'm not sure who has the Cloudflare logins, but they are needed to access the Cloudflare logs to determine what the problem is.
ChatGPT suggests that a likely build blocker is builtin documentation generation: main still uses the old command, while PR #157 switches to the required roc docs --builtins.

Anton (Oct 13 2026 at 12:38):

I am looking at the cloudflare build failure, the website is out of date because of the large amount of breaking Roc changes, things that break after updating and other random issues.

Anton (Oct 13 2026 at 12:41):

it might be time to organize a docathon to update all the docs?

Richard mentioned (I'm paraphrasing) in the last meetup that he's opinionated about the docs, so we want to make sure that we're not just filling out the docs in a distributed effort.

Anton (Oct 13 2026 at 14:34):

The website has been successfully updated :tada:

Aurélien Geron (Oct 13 2026 at 17:59):

Sounds good, thanks @Anton.

TeaDrinkingProgrammer (Oct 14 2026 at 06:57):

As I mentioned previously, I would like to contribute too, but I don't write Roc (yet) so feel free to tag me as a reviewer. Might even be helpful to have a perspective from someone who is not in the weeds as much. I'll also see id I can push my previous feedback as PRs

Aurélien Geron (Oct 15 2026 at 10:15):

I've submitted PR #163 to organize the Examples page into sections and give each example a little description:

Aurélien Geron (Oct 15 2026 at 10:24):

I also submitted PR #310 with 26 new examples covering more Roc language features, packages, and platforms:

Types and functions

• NominalTypes — nominal and opaque types.
• NestedTypes — types defined inside other types.
• OpenRecords — accepting records with additional fields.
• PatternAliases — naming an entire matched pattern.
• Closures — capturing values in functions.
• Boxes — using Box.
• RecursiveTypes — recursive and mutually recursive types.
• MutualRecursion — mutually recursive functions and tail calls.
• Polymorphism — where constraints and reusable aliases.
• DerivedMap — deriving map and map!.
• CustomEquality — custom equality and hashing.
• CustomOperators — arithmetic, comparison, and range operators.

Collections and iteration

• Sets — working with sets.
• Loops — for, while, var, and fold.
• Iterators — custom iterators, lazy pipelines, and ranges.
• Streams — stream pipelines, for!, and custom file-reading streams.

Error handling

• ExpectTry — using ? inside expect.
• WrappingArithmetic — handling overflow with wrapping and saturating arithmetic.

Parsing and encoding

• StringPatterns — capturing filenames and parsing path IDs.
• AdvancedParsing — optional fields, defaults, and parsing formats.

Organizing and publishing code

• Documentation — generating documentation with roc docs.
• PackageAuthoring — creating and bundling a package.
• PlatformAuthoring — writing C, Zig, and Rust hosts.

Packages

• Paths — using the path package.
• Unicode — graphemes, scalars, word boundaries, and casing.

Platforms

• RocRay — an interactive graphical application.

Aurélien Geron (Oct 15 2026 at 10:40):

I put them all in one PR for convenience, but if you want me to break it into smaller chunks, please let me know.

Last updated: Oct 15 2026 at 17:56 UTC