Here’s the final report, referring to the set of objectives stated in the original proposal. Monthly reports are here for April and this one for May.
Well, this was kind of ambitious. There are now 25 issues which were
opened in 2015 and 2016, but most of them are marked either
wishlist, external or NOT-SPECCED.
These are the issues closed per creation year, during and before the grant.
| Year | Issues |
|---|---|
| 2015 | 9 |
| 2016 | 65 |
| 2017 | 65 |
| 2018 | 179 |
I have checked out all issues in 2015 and 2016, and most issues in
2017, labeling them, in some cases commenting. However, there’s a lot
of work to be done, mostly in big issues such
as
this one on exceptions. I
have, however, happily contributed to
closing the roadmap issue
by creating all remaining pages.
More needed pages appeared after closing that one, but they are in other issues and are left for future work.
Issue and pull request templates have been added to the site. The style guides, have been updated several times, and now include a Squashathon Howto.
Several tests have been added: testing fake links, normalizes some words. Tests have been ordered and reorganized.
In general, this objective has been pretty much achieved, but there’s still a lot of work to do.
Well, I simply could not do this. I realized very soon that people want to work on whatever they feel like working, and assigning issues in general is considered rather rude. I did highlight some issues to be worked on during the Squashathon, and decided on labeling as “help needed” a single issue. I highlighted some issues in the IRC channel, to very little success. Most issues are not assigned, and most commits still do not match an issue. But that’s the nature of volunteer work. You have to live with that.
I could not find a way to do this, and besides, there are very good pages that do that, like Perl 6 Intro. I did create an article on the Perl 6 squashathon, and how to help with the documentation. I also helped with every day Stack Overflow questions, which are probably a better resource for newcomers. Instead of a single page, creating several possible entry channels is a much better strategy.
A talk on Perl 6 documentation has been submitted, and accepted, for the Dutch Perl Workshop, and again at the Perl 6 conference in Glasgow, which is yet to be accepted.
Besides the articles mentioned above, on the Perl 6 squashathon, and how to help with the documentation, I have tried to talk about it in comments such as this one or this one. I did contribute several tutorials among these about #perl6 in dev.to, but that was before the grant. I will definitely write more in the future, as well as update my book to help newcomers to the language, and also attract newcomers by making Perl 6 their first language.
It is difficult to assess right now. As indicated in the May report, there is record interest in StackOverflow and record visits in the website during these two months. I have put a lot of effort to the point of annoyance insisting that people post their questions in StackOverflow, so that the language is exposed to the wide programming community. It remains to be seen if this trend sustains itself in the future. I’ll continue staking out StackOverflow answering questions, and also looking for possible documentation errors or missing parts to work on them, and improve the documentation even more.
On the two missing deliverables: the statistics are good in general, but do not allow a fine analysis on the path followed, and what people are looking for. The main pages are the language page, and the one on operators. An attempt to add Google Analytics was met with opposition, and usability does not seem to be a big concern. So the deliverable on this area would be “This is not needed or wanted”.
On the second deliverable, well, I did create the following entry-level “tutorials”:
But they are in the documentation site, which makes easier to find them and also link them to the rest of the pages. In general, as I say above, entry-level tutorials are welcome, but they have a lower priority than finishing or starting much-needed tutorials which are part of the documentation.
In general, I would say that the main objective of this grant, which was to improve the documentation, was achieved, not only by closing the outstanding issues, but also playing attention to channels where Perl 6 is mentioned and creating issues on the repo when it was needed. The work on mining the repository has allowed me, and maybe the whole community through the published reports, to understand how this fully volunteer works and how work done is matched to work needed, which, in general, happens in a self-organized way.
I have laid out the foundations for helping this repo in a more relaxed way in the future, and also analyze the dynamics of the repository and propose some focused work in the future, in the framework of things like the Google Summer of Code, Hacktoberfest or any other world-wide event, funded or not, where people can contribute to repositories. This will help getting more work done in the future, and prioritize issues so that time devoted by myself, and others, to the repo is optimized.