One for the brag sheet:

I finished the documentation project I’d alluded to last October. Several weeks ater setting out to draft some initial standards for Perl’s core documentation, I returned with a proposed style guide and a set of research notes.

After several more weeks of discussion with many smart people, I can proudly report that the language’s maintainers accepted a revised and improved version of the document into Perl’s main version-control branch. Starting with the next release of Perl—that’ll be version 5.34, by my clock—you’ll be able to type man perldocstyle on your command line and see my writing. (And in the meantime, you can preview it on Perl’s documentation website.) Not bad!

Next comes the hard part. I included among my research notes the recommendation that Perl launch its own documentation sub-project, led by its own small team, in the pattern of every other language or FOSS project that I studied for this work. Over the holidays, I’ve been in touch with Perl’s maintenance team as well as Perl’s brand-new steering council with a proposal for such a body.

Obviously, this conversation is only just beginning, but I’ve reason to feel encouraged already. In the interim, I send my love and respect to the Rust, Python, Raku, and Linux Kernel documentation teams, all of whom unwittingly contributed to this ongoing project through their respectively excellent and open work. And, of course, my gratitude goes out to The Perl Foundation for funding this work in the first place.

This article was also posted to the “programming” section of

Share or reply to this post on Twitter, or elsewhere.

Next post: What needs to happen now

Previous post: I read some of The Outside

Loading responses...

Share a response

To share a response that links to this page from somewhere else on the web, paste its URL here.