I'm sorry, but I'm voting -1 on this grant proposal.
First, by far the most major issue with the docs repo is the generation of the static website. It's done using less-than-ideal piece of code that has issues and limits what we can offer on the site. Briefly looking at the list of open issues, about 30% of them concern the site/build (build, 37), (site, 23), (search, 15), (wishlist, 14).
I don't believe we'd benefit by keeping that piece of code and should instead make a dynamic site, which would let us address many issues, such as more advanced search and better categorization. The best I can understand the proposal, such big changes are not on the table and probably the 40% of the issues offered to be fixed would involve modifying the existing system (or not address this part at all).
----
I also believe the promise to address 5 doc issues per day, to a total of 120 is a bit ambitious for a single person to do. In my experience of working with the docs repo, a lot of the documentation-writing issues actually go all the way to language design, since what's implemented by Rakudo does not define correct behaviour of Perl 6. We have a separate specification and the docs document that specification.
For many docs Issues, the @LARRY core devs would need to make language design decisions that would then percolate into specification clarification (presumably including implementation, to ensure the decision works well), and only then would the specced behaviour be documented.
I'm a bit worried the grantee would simply document Rakudo's behaviour, rather than what's actually specced.
----
I hope it won't come across as any form of an attack, but I have some concerns about grantee's actual suitability to resolve some of the docs issues. As an example, they recently resolved Issue #949 ( https://github.com/perl6/doc/issues/949 ). The Issue is a year and a half old, and essentially says "Move programs/00-running to rakudo wiki". That's precisely what the grantee performed, however, since the Issue's creation the 00-running page has grown considerably and included several non-Rakudo-specific documentation that the grantee still moved to the Rakudo wiki. When that was pointed out, the grantee explained themselves, saying "What the title said was precisely what was done, move it to the wiki."
Personally, I would expect someone who wishes to close 120 (40%) of the repo's Issues to give more thought to those Issues, and to evaluate whether they should [still] be addressed, rather than simply follow them as instructions.
Also, some of the mentioned deliverables already exists. Such as the visitor statistics ( http://www.p6c.org/stats/doc.perl6.org ) and contribution guidelines ( https://github.com/perl6/doc/blob/master/CONTRIBUTING.md#general-principles ). It's unclear if the grantee is unaware of these resources or simply meant to produce something different.
Lastly, clarifying documentation based on users' questions is something IRC regulars already consistently perform, which is why I find it a bit odd to be listed as a deliverable on a grant.
----
My 2¢.
Cheers,
ZZ
+1
JJ Merelo has done a lot of this work already recently (thanks, JJ, for the effort!), and it did cost him a lot of time, and it is paying off already, documentation is already improved. Lots more needs to be done, and a grant would be appropriat and necessary.
Definitely +1
I feel so conflicted about this. At first I was very happy to see potential dedicated effort for improving the doc repo, but this particular proposal does not look right. I think that details about this proposal should have been discussed with the community before applying for the grant.
As for JJ, I'm fairly satisfied with their work on the doc repo. Zoffix mentions one of the mistakes during their recent efforts, but we have to keep in mind that this is about very old issues that have to be kicked around quite hard in order to get them moving. I think there's no issue with suitability, and JJ is open to feedback and seems to adjust accordingly whenever there is any.
The biggest issue here is in the proposal itself. Some comments:
“creating a set of rules for existing and new contributions and enforce those rules in the test suite”
This is the second thing being presented, and it seems a bit controversial. While there's a constant flow of contributions to the doc repo, the amount of tickets seems to suggest that it is not enough. But are we saying here that we will be adding rules to make contributing even harder? If not, why? And in any case, where is the community discussion on this? I don't think we should be learning about this problem from the grant proposal and not a corresponding ticket.
“assigning outstanding issues during the grant and create a system for assigning work to volunteers”
You can already assign people on github, but this does not seem to be very effective. Again, I'm failing to see any ticket with a discussion on this topic, like why is this needed and how is it supposed to work even.
“creating an entry page with a tutorial for complete beginners with very little or no knowledge of programming, with the intent of providing a good landing page for the language”
This sounds pretty good, but so far the consensus has been that we can just link to one of the many existing resources (like http://perl6intro.com/ ). This is discussed more on https://github.com/perl6/doc/issues/114
“contributing to Perl and general open source conferences with entry-level tutorials and learning material, and”
To me this seems to be off-topic, just like some other things in this proposal. Some of this, by the way, already exists in the marketing repo: https://github.com/perl6/marketing (like Introducing-Perl6-Brochure).
“writing articles in websites such as The Practical Dev (https://dev.to), HackerNoon or Medium with practical "30 minutes" tutorials to perform usual tasks in Perl6.”
I'm fully against this. Not only we already have many resources like this, but it also goes against the vision we have for the doc repo: “I want p6doc and doc.perl6.org to become the No. 1 resource to consult when you want to know something about a Perl 6 feature, be it from the language, or built-in types and routines. I want it to be useful to every Perl 6 programmer.”
So personally I'm expecting *all* of the deliverables to be within the perl6 organization on github (doc repo mostly).
“Addressing 5 doc issues per day on average, minimum 2 issues per day. Reduce the amount of open issues by at least 120.”
This is indeed very optimistic. Every second month there is a 50-hour doc squashathon, and it seems that all low-hanging fruits were already collected (see https://github.com/rakudo/rakudo/wiki/Monthly-Bug-Squash-Day ). This was definitely possible last year, but today it would be very difficult, especially given that this proposal has **many** other deliverables.
“Day 7: identify core of people working on the documentation and create an open channel of communication, for instance, a Telegram channel with the GitHub bot connected”
This is unacceptable. The main communication medium for perl 6 development has always been IRC, and there's no good reason whatsoever to be committing to Telegram without consensus. Anyone should feel free to use Telegram by bridging the corresponding IRC channel through the Matrix network, but in no way we should be requiring use of yet another messenger for basic development.
To be honest, I can go on and on, there are just too many things in this proposal that are weird, controversial, potentially useless or just possibly harmful.
I think that the proposal in this particular state should be rejected, but I hope it would be possible to have a new one once all details are discussed with the community. In other words +1 for JJ and their current and future work, but -1 on that particular grant proposal.
Just in case this is accepted, I think the choice for the grant manager should be different than what is presented. I'd personally nominate Zoffix Znet, Moritz Lenz, Will Coke Coleda.
How will it compare with brian d foy’s book?
Thanks for the feedback. I respect your work enormously, and can only accept with a smile your criticism. But if I may, let me address your concerns, hoping to sway your support, if that's still possible. Besides, I intend to keep working just the way I have done so far with or without grant; the grant will allow me to work with more intensity and stay 2-3 days at home from office to work full-time on this, but one way or the other, the criticism is always welcome, respected and accepted.
First, it's quite clear to me that there are several layers in the documentation of a language and that they need to be taken care of separately. In the case of Perl6, there's the added layer of the website itself, which is also included in the same repository. Then there're tests, and then of course the documents themselves. I haven't been working on the first, but I do have at least some ideas on how to improve testing; I have worked on the travis configuration to make testing faster and I have opened an issue to streamline tests and create some specific auxiliary library to work on that and make writing new tests faster and safer. Baseline is, I don't intend to get in the way of whatever direction the tooling/web layer is eventually taken. My only intention is to help and make easier to get there. Please bear in mind that I don't intend to distinguish between some issues or the other or be adamant or vocal about some particular posture. My intention is to address issues and help them get acted upon, either by myself or by others.
I don't believe we'd benefit by keeping that piece of code and should instead make a dynamic site, which would let us address many issues, such as more advanced search and better categorization. The best I can understand the proposal, such big changes are not on the table and probably the 40% of the issues offered to be fixed would involve modifying the existing system (or not address this part at all).
I also believe the promise to address 5 doc issues per day, to a total of 120 is a bit ambitious for a single person to do.
The Issue is a year and a half old, and essentially says "Move programs/00-running to rakudo wiki". That's precisely what the grantee performed, however, since the Issue's creation the 00-running page has grown considerably and included several non-Rakudo-specific documentation that the grantee still moved to the Rakudo wiki. When that was pointed out, the grantee explained themselves, saying "What the title said was precisely what was done, move it to the wiki."
Also, some of the mentioned deliverables already exists. Such as the visitor statistics ( http://www.p6c.org/stats/doc.perl6.org ) and contribution guidelines ( https://github.com/perl6/doc/blob/master/CONTRIBUTING.md#general-principles ). It's unclear if the grantee is unaware of these resources or simply meant to produce something different.
"Might not be an attack, but it still hurts."
Sorry about that. Perhaps, I was overly critical, given I haven't been closely following your other work in the repo.
"and even creating issue templates that can help make issues a bit more usable."
"creating a set of rules for existing and new contributions and enforce those rules in the test suite"
I think this is exactly what AlexDaniel++'s comments highlight: lack of previous community discussion regarding some of the items in this proposal. Issue templates and enforcing rules on new contributions were already discussed by the community in the past and the currently-implemented system where a select volunteer fixes xt/ failures once a month, instead of forcing all contributors to follow rules encoded by those tests is the result of that discussion.
In fact, reading AlexDaniel++'s comments, I think they're a lot more to the point than my original ones and I agree with all of them (with the exception of having me as a potential grant manager; I nominate AlexDaniel instead of me)
Thanks a lot for your answer and suggestions. I tend to agree with them, but still, I have to try and take a stand for my proposal. I have been trying to discuss many issues in the Facebook group and in issues, and the answer has been underwhelming. If this grant proposal is the vehicle to bring some issues in the open, so be it. As I said, I am not adamant about those things that I have proposed and what you criticize is mainly peripheral to the main issue, that would be to try and work, purposefully and part time, in the doc repository, obviously working with what and who's been already there doing a great work. So let's go issue by issue and see if I can try and explain why I put them there
creating a set of rules for existing and new contributions and enforce those rules in the test suite
To tell you the truth, when I prepared the proposal I wasn't aware of the xt test suite. I discovered it a few days ago, when I was preparing the Travis configuration. I kinda found out that it was run from time to time, basically when the dictionary was updated. So I think we can scratch that pretty safely, since that's pretty much being done.
“assigning outstanding issues during the grant and create a system for assigning work to volunteers”
You can already assign people on github, but this does not seem to be very effective. Again, I'm failing to see any ticket with a discussion on this topic, like why is this needed and how is it supposed to work even.
We're having the discussion here, right? Right now changes and discussion take place in the general #perl6 channel; I would try and go for a exclusive channel. It can be Telegram or something else. The channel is not the point, anyway. Most of the issues are not assigned; some people self-assign issues and work on them; some work on them without even assigning it. There should be some way of assigning and committing to issues. This is simply no way to push development forward, and it shows in issues like this one https://github.com/perl6/doc/issues/561, which is part of a web of "broken link" issues and seems kind of critical, and it's not even assigned, even if it was opened 2 years ago.
There are also ~ 12 issues related to pragmas, and I have inserted some comments here and there, but there seems to be no one wanting to take up the challenge. My intention with this grant was to be the person to take those major documentation milestones, involving several issues and which have been dormant for a long time. You are right that creating new channels is possibly harmful, but that's not the intent of this point. The intent is to identify potential issues and get them assigned to someone, or do them myself if needed.
“creating an entry page with a tutorial for complete beginners with very little or no knowledge of programming, with the intent of providing a good landing page for the language”
This sounds pretty good, but so far the consensus has been that we can just link to one of the many existing resources (like http://perl6intro.com/ ). This is discussed more on https://github.com/perl6/doc/issues/114
No big deal. My hands are full enough. But you mention that issue, which is one that should be addressed also sooner or later. See my last comment about pragmas. Creating a page with links to the documentation is good SEO anyway. But I can really make do without that. Same about the next issues. Writing things outside the repo is probably off topic, but it can't hurt to have more people approach the language and community. I'm OK with doing all deliverables within the organization.
“Addressing 5 doc issues per day on average, minimum 2 issues per day. Reduce the amount of open issues by at least 120.”
You say that it's optimistic, but I did that quantity on my past experience. Not all issues are #114. Most issues are a matter of changing a couple of lines. Addressing 5 is what I try and do every weekend, on average...
I am willing to change whatever details you think, and of course, work with whoever is assigned to me as a manager, and I would really want either Alex, Zoffix or Coke to be. I'd love to work with you and learn from you, and you can keep an eye of me to check that I'm not doing anything (too) wrong. Since you don't get to nominate managers, you can't just send the hot potato to each other; it's me who nominate them, and I nominate both of you.
I am obviously ready and able to prepare it for next round if that's your will. And to keep learning and working on the documentation meanwhile.
If the discussion shows something is that there is a huge need for this kind of work to make Perl6 --a huge language!-- accessible to newcomers. However, there is no community consensus on how to tackle the problem and consultation may be needed. It's also true that in FOSS communities discussions tend to go on forever until someone steps up and does a big part of the work. This is what JJ is doing in this case (imho).
If it's possible within the grant system, I would adapt the goals slightly to acknowledge the input given here. Narrowing the scope somewhat (e.g. concentrating on what's missing/broken on doc & the backlog, while identifying future paths) may be an step in the good direction. The people in this discussion can provide the needed input, e.g. on #perl6.
+1 on the proposal with some adaptations (and JJ+ for the job already done).
C.
Thanks a lot for your feedback, Claudio. I am obviously open to any modification, and of course I value all feedback received and would try again next time if it's not granted this one.
As a newcomer to Perl6 (about year ago). I found the documentation be messy and unstructured, but seems that I'm getting to used to it.
Fresh layout, structuring, better indexing would be very welcome. And seems that finding with Google search engine from these pages is difficult also, I find myself searching same thing over and over again.
So yes, big +1 for this.