season-of-docs-ideas

Big issues in Raku documentation

Description

Raku documentation was, from the beginning, decoupled from language development. It started much later than language itself, and mainly written by people not directly involved in the programming effort itself. This essentially resulted in a de-synchronization of language features and the documentation they would need to actually be used, with relatively wide areas of the language uncovered, or poorly covered, by documentation.

Issues related to these areas were marked as big, because they usually involved creating many new pages from scratch, or creating tutorials for features that had not, so far, been documented.

In this case, documentation involves good skills in reading source code that implement features, but also proactivity requesting tests or raising issues when the implementation is incosistent, does not behave as expected, or untested. In general, that implies that those big issues require a degree of effort that has left them, in general, unadressed for long periods of time, as much as three years in some cases.

The written documentation must follow a series of standards (many of which are tested automatically), but working in these big issues allow a certain degree of creative freedom; this is why this is considered a more attractive project that small issues that need a lot of research.

There are many other issues, however. While working on a specific big issue, we would try to draw the attention of the writer to other outstanding issued in the same area, that could maybe be solved at the same time or with the expertise acquired solving these big projects. Some of these issues are actually linked on the big issue page, so they’re not difficult to identify.

Expected outcomes

Required skills

Required or prefered skills the person should have to be able to tackle this project.

Rating

Medium.

Possible mentors