Grant Proposal: Curating and improving Perl6 documentation

Category: Grants

Comments (11)


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 haven't proposed either keeping it or taking it in another direction. If you want to make it dynamic, I'm all for it, and I'll try and make sure those issues are addressed; if I can help with programming, I'll do it, by all means. They are not on the table, but they are not off the table either. I don't think I can all by myself take the documentation in a new direction, but if rough consensus and working code decide to take it there, I'll do my best to help with that.
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.

I'm saying specifically address. The problem with many issues is that, as you say below, have outlived their usefulness or have maybe even been fixed somewhere without nobody noticing. Addressing means pinging the issue, see if someone can take care of it better than me (which is usually the case), check if it's been solved, if it's still relevant, and then take a decision on either solve it or change. The problem with most issues is that they are not assigned to anyone, so no one is actually committed to do anything with them. Having a manageable amount of issues helps establish priorities and solve important things better and faster than easy things. My experience so far is, even if I'm devoting one hour or two per day, is that I can address 2-3 issues per day, up to an including fixing them in many cases. 120 issues which is the minimum and would barely make a dent in the issue list is 2x60, which is my commitment and I think can be done. You can check my track record in this repo (or, for that matter, in any other) if you want to see whether this is a realistic estimation or is actually off the mark. I could start, for instance, getting some crew of active volunteers and assign issues, which are not assigned in 90% of the cases https://github.com/perl6/doc/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20no%3Aassignee.
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."

Might not be an attack, but it still hurts. I spend around one hour moving this to the wiki, following exactly what the issue said. Before doing that, I spent some time in the issue, pinged it, asked what would be done https://github.com/perl6/doc/issues/949. If the language and the page evolved during those almost 18 months, it's exactly my point and the problem that I want to address: old issues that have outlived their usefulness, but they are still kept open, to what end I really have no idea, since what the issue says is no longer relevant and documenting whatever was there is a completely different issue.
Still, that's only of the issues I have addressed or closed. I have closed 9 issues so far, and closed others that have been reopened later on, and addressed quite a few. I can address many more if I devote myself fully to this, at least a few days a week. I get your point that you need to see the full picture in many cases, but it's quite clear that I will not be isolated and will rely on the community when it's a tough call. It's what I have done so far...
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.

Paraphrasing you, it's unclear whether you misread what I proposed to deliver or simply want to use another angle. Those stats are not Google Analytics, and simply don't allow to visualize visitor paths (which is what I said) and site usability. Page views per visit http://www.p6c.org/stats/doc.perl6.org#Pageviews%20per%20visit tell us that almost half the people visit a single page. Is it because they don't find what they are looking for? Or exactly the opposite? Taking into account that the most visited page is /, what does it tell us? Can we improve on that? The thing with contributing is that so far most contributions are not evaluated on an one-to-one basis, with extended tests run only from time to time. They also include some very strong guidelines on some aspects, but not on others, which means that in some occasions, examples could be improved; we only find which ones when someone lands on them. I was well aware of that file as well as the tests (in xt/) that check if some of those guidelines are met, but my intention was to extend it a bit further and even creating issue templates that can help make issues a bit more usable.

At the end of the day, I tend to agree with you. I'm probably not the best person out there to tame the documentation monster. But you have to agree with me that there are literally, some issues with the documentation and it would help to address them. But also we have to ask ourselves: are we getting through to new and jaded users? Are we serving them with the best documentation out there? Can we do a little bit better? I think I can help, if maybe just a little tiny bit. As I said, I'll be doing it anyway, because I love Perl6 and I love the community. But having the grant will help me focus on this and not have it as something you do after a long day of grading assignments and writing papers.


"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.


Sign in to add comment