Apocrypha: stories about Perl 6 documentation

Juan Julián Merelo-Guervós — 45 minutes 🦋

Perl 6 has a peculiar, all volunteer, model of documenting the language. This talk will explain the history of Perl 6 documentation, the state it is now, and how it might navigate into the future. It also hopes to shed some light on how documentation is the one of the things that binds the community together, how to look at it as a Perl application, and also what you can learn from documenting and how documentation is written for making your own applications (and its documentation) better.

If there's a single decision that made Perl 6 documentation the way it is today, is the fact that Pod6 (the Perl 6 documentation) is actually a minilang that is parsed by Perl 6 itself. That, in turn, meant that adding documentation to the Rakudo code made compilation slower, so documentation was spun off to another repository, implying that, in general, the people who wrote the documentation were different from the people that actually coded the features.
Documentation was thus started in a repo in 2012 by Moritz Stefaner, and from then it proceeded as a (n almost completely) volunteer effort. The documentation was published on the web, which needed a series of tools; it also needed a command, p6doc, which also used a series of tools. Tools and documentation became entangled in a way that, come this point, is kind of difficult to unravel.
This talk will basically be the history of my involvement with the Perl 6 documentation, which has been going on for more than a year. We will look at the history of the repo, and offer data on how people has been involved with it through time. We will also look at the current state of tooling and source, and finally, we will offer some hints (and request for help) about how it will go into the future.
This will be a talk about community, tools, what makes Perl 6 great, and what makes development of Perl 6 (and surrounding tools) interesting in different ways. Eventually, you might learn some lessons about the importance of documentation, the importance of the community, low-level Perl 6 features you might not be aware of, and what and how sustainability might be achieved.



Talk tags
perl 6, documentation, tool the docs.
Perl versions
🦋 Perl 6
Target audience
Beginners
Talk duration
45 minutes
Talk status
pending
Related links

https://github.com/perl6/doc