Squashing Raku documentation bugs, one at a time

The monthly community bug SQUASHathon starts tomorrow at 11 CET. And you can help.

Bugs are nasty things

But who's free of them? Not the Perl 6 documentation, which is going to be the focus of this hackathon. This repository contains the documentation and tooling to publish it in docs.modules.org.

This is the official documentation of the language. Your contributions will become part of the official documentation for the Perl 6 language. Can you imagine that? Yes you can! Because you can, and will, help in this hackathon!

How can you help?

The hackathon will last for 50 hours, finishing on Sunday morning, Western European time (it will vary in different timezones). You can join any time you want, leave any time you want, work with as many bugs as you want. Coordination will be done through the #perl6 and #perl6-dev channels, so if you feel lost, or need some help or orientation, fire up your IRC client and ask around; somebody will be there to help. You can also dive directly into one of the issues, starting if you will with good first issues. Drop a comment in the issue you're interested in and ask someone to assign it to you, so that nobody else steps on your work. When you're done, submit a pull request. The PR will be reviewed, and eventually accepted! Thanks for asking and for the contribution.

Now, really, how can I help?

Perl 6 is a relatively new language, and it is likely that you haven't heard of it so far. That need not be an obstacle to collaborate in the documentation. You can learn it along, and you will find it easier to learn by reading the material and helping with it or the examples. The language of the documentation is English, and you probably know English already. But here are a few things you can do to help

• It will help to read through the CONTRIBUTING file in the repository if you will be writing new material, examples, and maybe even new pages.
• The gentle introduction to Perl 6 is not going to hurt. At least have a general idea of how the language works, at least so that you can understand the general mechanics of the examples in the documentation.
• Perl 6 documentation is written in Perl 6 POD. It is a markup language that includes the usual things: blocks, emphasis, and code examples. You will recognize it in lines starting with =. You don't need to learn the whole language, but at least understand how it's rendered to HTML will always help.
• It's convenient that you have Perl 6 installed, just in case you want to test-run an example or actually build the documentation in your system. The recommended way is to use Rakudo star, a ready-to-install distribution in binary form for any operating system.

I just have half an hour, but I want to help!

You're very welcome! The intention of the hackathon is to improve the documentation, and documentation is intended for developers that are not familiar with the language (as it should be). So you can help by trying to find out how something is done in Perl 6, and seeing if the documentation adequately describes what has to be done. Think about any language construct or particular task, search for it in Google, see if you land in the Perl 6 documentation pages; if you do not, you can file an issue saying that the documentation is not well positioned; if you do and the documentation page does not really cut it, file an issue stating where we lost you: too complicated language, examples not clear enough... Whatever was the problem. Issues also help to improve the site, and maybe it's easy enough somebody else participating in the hackathon can help!

I have the whole weekend, I really want to help!

You're very welcome! The problem with writing documentation for a language is, well, it's not about rehashing other documents, there's literally no documentation for it. If you want to document a function, or a type, that is not documented, here's how you can find what it actually does. Most of it includes searching in GitHub, so you will need to have an account there.

1. Do a general web search, or in particular in the Perl 6 Advent Calendars. There have been Advent Calendars since December 2009; some of them talk about experimental features, and not all of them made it into the general documentation, so there might be some stuff there that is not here.

2. If you are already in one of the IRC channels, you can use the helpful bots to search for the code. As AlexDaniel says, greppable will search through the repositories and find the source code you are looking for. Once in the IRC channel, write: greppable: CompUnit, which will answer something like greppable6 | jmerelo, 10251 lines, 698 modules: https://gist.github.com/35124b916a96e596a18786b8fe318d71 (you can check that gist, it's permanent and still there). This will help you to search through all the repositories. If you don't want to disturb the rest of the channel (there's no problem is you do so, and someone else could help), use the #whateverable channel on freenode. This bot, as well as the rest of its siblings, is available there as well.

3. Search for it in the general Github search. When has the fact that something is not documented stopped anyone from using it? In some cases, you will find the type used in actual code, and you will have an example ready to use, or use an issue to ask the author what's the intent and effect of that code. Reduce the search to Code and use language:"Perl 6", to constrain your search, of course.

4. Search for the function or type in roast, the Perl 6 test repository. If it's in the language, it's got to be in roast. If you have done the search above, you will have probably found this already, but you can also focus on it to check different implementations.

5. Search for the source code in the Rakudo repository. Rakudo is the Perl 6 compiler, and it's mostly written in Perl 6 and something called Not quite perl. It's, well, not quite Perl but if you can at least read the source code you will be able to understand it enough for solving the not-documented-feature issue.

If you do that, that will be really great. And you will help Camelia and the free software community at large.

I really don't have time, but I still want to help. See, I have an Avengers marathon this weekend and...

No worries. Just spread the word in your favorite social networks. Use the #perl6 and #squashathon hashtags, and it will get to someone who's seen already all the Avengers movies, will be kind enough not to spoil it for you, and also will be able to help in this particular hackathon. You're very welcome too!