Perl 6 documentation: past, present and (possible) future or futures

When it was designed, Perl 6 chose a very clear path for its documentation, the path of “Documentation is a great thing. Somebody will have to do that, eventually”. In this paper we’ll see how that worked out in the end, what lessons we draw from it, and how to carry that to the future.

Unlike many free software projects where the same people write the code and the documentation for it, it was a design decision from the beginning that documentation of Perl 6, its classes and more meta stuff, would be clearly separated from the interpreter (and the rest of the parts of Perl 6) itself. A documentation repository was created by Moritz Lenz, who started to hammer away at writing down what every piece of Perl 6 did, and how to put together programs and modules that use it. This documentation repository eventually became host to three different things: the source of the documentation itself, written in Pod6, a SLANG within Perl 6 for documentation, but also the command that indexes and shows that documentation, a series of modules that process and extract metadata and source from that documentation to generate a static website, and the application (in Perl 5) that publishes that site itself. The management of the site became a do-ocracy, with anyone with a commit bit deciding on where to go next, which issues to address, which PRs to accept, in a model that is actually not so different from the rest of the Perl 6 ecosystem, but which makes sustainable and, over all, long term development, a challenge. In this talk we will first analyze the model of Perl 6 documentation and what kind of lessons can be learned from it for software development at large, and Perl and Perl 6 development in particular. Then we will analyze data on contributions to the Perl 6 documentation repository and see how this software development model has worked out, what it lacks and what can be done to improve it just a tiny bit. Finally, we will check out the architecture of the Perl 6 documentation processing systems, and try to create a roadmap on how it could be further developed in order to optimize the performance, and also the performance of the available volunteer resources.

I started to work on Perl 6 documentation during late 2017, when I was starting to prepare some course material for it, which eventually became a book. There were many parts missing, and this led me to a rabbit hole that inspired me to request a grant for working on that. The Perl Foundation gratiously gave me the grant, and I was working on it for a couple of months, finishing in May 2018. Since then, I have working daily in the documentation and tooling, and arguably leading the project, or at least doing the most contributions to it during that period. I have also been in the Perl community since 1993, founded Granada, my home town, Perl Mongers, and attended and given talks in several YAPCs in Europe, Perl workshops in London, Barcelona, Granada and the Netherlands, and contributed to the Perl devroom. I have also contributed to one Perl Advent Calendar and two Perl 6 Advent Calendars (and coordinated the last edition) I will just need the usual beamer, and if possible, a clicker since I like to roam while talking.