Inviting community to mass edit selected lessons

[ianmilligan1]

I had a great chat with @gvwilson today, about trying to find areas of inspiration from them (and them in turn some inspiration from our more formal process of incubating lessons).

One idea was to try to open up Programming Historian a bit more to public edit. Right now, while we certainly accept pull requests and suggestions, the sense of authorial ownership is so strong that people may not realize just how editable it all is.

So a proposal: why don't we designate three or four lessons, put a banner on the top of the lesson, and really encourage people to review contributions along the lines of a blitz?

Similar to the hypothesis experiment, but with an explicit invitation to think of these as community resources that we're happy to see edits too (a la Wikipedia). And everybody who has a pull request/comment/etc. accepted, we could add a little line in the header just to note the contributions, while still maintaining the primacy of the original author and review team?

By doing so, maybe we could get the ball rolling a bit more – make a firm statement that everybody has a good moral permission to edit/take ownership/etc. over lessons, that they're not stepping on toes?

[ianmilligan1]

I have talked with @drjwbaker and we are happy to use our intro to bash lessons as a guinea pig. Any other takers, if people think this is an idea worth pursuing? 😄

[acrymble]

Interesting idea. What's the objective?

It sounds like a lot of editorial work, and a redefinition of authorship that might put off some contributors. Especially if lessons get broken by well-meaning people.

Maybe you can outline what you hope it will achieve so we have a clear sense?

[ianmilligan1]

We've had struggles with keeping lesson up to date, which puts a lot on authors. This might help move us more towards a community-maintained resource.

I should note that I'd be happy to run with this, esp. with a small trial.

[fredgibbs]

I really like a lot of these ideas. I agree we can and should to do more—actively, since the documentation is quite clear— to highlight the availability and necessity of community participation that help keep our lesson useful over time. I would suggest focusing on bringing attention to or featuring one lesson at a time for a week-long (or whatever) blitz review. I think we’d be spreading ourselves too thin and unnecessarily distributing editing energy across too many lessons otherwise. If we’re trying to foster a greater sense of community, I think having everyone know that they are thinking about and going through the same lesson is more effective than if there are a handful to choose from (and that we need to promote via Twitter, etc). This could perhaps be tied into the Slack channel editing suggestion process we’re still trying to optimize.

I agree with Adam that one incentive to write a lesson is by-line atop the lesson page. So as not to devalue that, I would say that later contributors should be featured at the end of the lesson (unless someone is doing a ton for the lesson, which may warrant special consideration). It maybe it doesn't offer quite as much incentive to contribute as being in the header (arguably, if people want that, they should write a lesson!), but I’d prefer to feature the must more substantial authorial, editorial, and review work at the top. And that way, contributors get a space all their own and don’t have to compete with everyone else for attention to their important work.

Fred Gibbs History Department University of New Mexico @fredgibbs https://twitter.com/fredgibbs || fredgibbs.net http://fredgibbs.net/

On Oct 28, 2016, at 9:48 AM, Ian Milligan notifications@github.com wrote:

We've had struggles with keeping lesson up to date, which puts a lot on authors. This might help move us more towards a community-maintained resource.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/programminghistorian/jekyll/issues/304#issuecomment-256956368, or mute the thread https://github.com/notifications/unsubscribe-auth/AAfdeN9bZvEMMQf4y8QoeNWvG9h4xYZFks5q4hlHgaJpZM4KjkUD.

[fredgibbs]

I forgot to mention that this might also help new and more experienced users work on lessons at the same time—potentially a great way to encourage new readership and forge community bonds.

Fred Gibbs History Department University of New Mexico @fredgibbs https://twitter.com/fredgibbs || fredgibbs.net http://fredgibbs.net/

On Oct 28, 2016, at 7:15 PM, Fred Gibbs fwgibbs@unm.edu wrote:

I really like a lot of these ideas. I agree we can and should to do more—actively, since the documentation is quite clear— to highlight the availability and necessity of community participation that help keep our lesson useful over time. I would suggest focusing on bringing attention to or featuring one lesson at a time for a week-long (or whatever) blitz review. I think we’d be spreading ourselves too thin and unnecessarily distributing editing energy across too many lessons otherwise. If we’re trying to foster a greater sense of community, I think having everyone know that they are thinking about and going through the same lesson is more effective than if there are a handful to choose from (and that we need to promote via Twitter, etc). This could perhaps be tied into the Slack channel editing suggestion process we’re still trying to optimize.

I agree with Adam that one incentive to write a lesson is by-line atop the lesson page. So as not to devalue that, I would say that later contributors should be featured at the end of the lesson (unless someone is doing a ton for the lesson, which may warrant special consideration). It maybe it doesn't offer quite as much incentive to contribute as being in the header (arguably, if people want that, they should write a lesson!), but I’d prefer to feature the must more substantial authorial, editorial, and review work at the top. And that way, contributors get a space all their own and don’t have to compete with everyone else for attention to their important work.

Fred Gibbs History Department University of New Mexico @fredgibbs https://twitter.com/fredgibbs || fredgibbs.net http://fredgibbs.net/

On Oct 28, 2016, at 9:48 AM, Ian Milligan <notifications@github.com mailto:notifications@github.com> wrote:

We've had struggles with keeping lesson up to date, which puts a lot on authors. This might help move us more towards a community-maintained resource.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/programminghistorian/jekyll/issues/304#issuecomment-256956368, or mute the thread https://github.com/notifications/unsubscribe-auth/AAfdeN9bZvEMMQf4y8QoeNWvG9h4xYZFks5q4hlHgaJpZM4KjkUD.

[gvwilson]

Software Carpentry and Data Carpentry treat lessons as if they were open source software: anyone who wants to propose a change can do so by creating a pull request, which is then reviewed, revised, and (if accepted) merged in. The original author(s) of the lesson, or their designated successors, act as maintainers or editors: they have final say over which PRs get merged and which don't. (They may review PRs themselves, or encourage others to do so.)

We publish our lessons twice a year, where "publish" means "tidy them up and get a DOI through Zenodo". When we create their bibliographic records, everyone who has had something merged is listed as a contributor, but the maintainers are also listed as editors, and past maintainers continue to be listed as editors even after they've handed the lesson over to someone else.

The strengths of this approach are that the community maintains the lessons (we've had about 400 distinct contributors in the past three years) and the editor-vs-contributor distinction allows us to recognize people who are doing extra work. Its weaknesses are that big changes are more difficult to make than they would be if there was a single author, and there's no incentive for people to do reviews: your name doesn't show up in the bibliographic record for a lesson if "all" you did was craft hundreds of lines of thoughtful feedback.

I have no idea how much of what works and what doesn't in SWC and DC is historical accident, and how much is intrinsic to our process. I think we could learn a lot from PH's more structured review and publication process, and I'm curious to see whether our PR-based model could help in the other direction.

[acrymble]

Thanks @gvwilson for this. That makes it much clearer.

@ianmilligan1 I suppose my only concern (apart from the moral rights of authors, which we have to be clear about - maybe on our contribute section?) is that I wouldn't want this to result in more work for me, especially because it's the type of work I don't like (dealing with fixes post-publication). And our past experience with Hypothesis shows we don't like doing it, because we still haven't incorporated those suggestions in all cases.

So can we do this with existing team members, or is this something we should recruit specifically for to ensure it gets done well by someone?

[gvwilson]

We've found that it's a good on-ramp for community members who want to get more involved, but aren't (yet) ready to write an entire lesson themselves - I'm no longer the maintainer/editor of any of the lessons I originally wrote, and in fact a couple of them have now "changed hands" twice.

[jerielizabeth]

I like this idea -- I know the beautiful soup lesson needs some attention (and an update for Python 3) but haven't had time to do it myself. I would be happy to also volunteer as a second test case if we want to do this.

I think having the author as the maintainer on the lesson, responsible for merging in pull request and reviewing suggestions goes a long way to maintain their "authorial rights" over the lesson. And @gvwilson's note that it is a great way for people who are interested in being involved but perhaps not at the full lesson point is really compelling. And I second Fred's idea of promoting one lesson at a time -- helps focus attention and gives the whole venture more of a chance of succeeding.

[jerielizabeth]

To further encourage this ... @celestetvs has a group of students who would be interested in contributing this way.

[wcaleb]

I also like the idea for reasons others have outlined. With regard to giving credit to contributors other than authors, it's perhaps worth noting that GitHub's ecosystem does much of this natively: anyone who submits "pull requests" for example, would have their handle show up in the "commit" history for the lesson, which is available from the "previous versions" link at the bottom of any lesson.

[ianmilligan1]

Great, Jeri (cool about student interest too, could be some built in attention for the first round..)!

I wonder if we could get contributors added somewhere in the lesson too, perhaps in the footer? (keeping authorial voice and prestige up in the header)

[wcaleb]

@ianmilligan1 If I can figure out a way to access GitHub API using small JavaScripts (as in #273), then that could be easy to do---just pull in a list of all people who have made edits to the lesson---and automating it would be easier to keep it up to date.

[gvwilson]

We run a small script every time we re-publish a Software Carpentry lesson (i.e., get the latest version a fresh DOI) that pulls author IDs out of the Git commit log and mailmap's them to names, so that the author list in the bibliographic record and the author list in the GitHub repo don't get out of sync. There are some false positives - people who've contributed to the lesson template, but not to this specific lesson, are included - but its biggest failing is that it doesn't give any credit to people who've invested time in doing reviews of contributions.

[wcaleb]

@gvwilson We do something similar to generate the list of community contributors on our Project Team page, with some of the same problems you mention.

[celestetvs]

thanks for looping me in @jerielizabeth! I have a small group of students who work on data problems/projects and have prior experience creating tutorials who I think would be quite good at providing suggestions for updates and improvements. I could direct them to particular lessons like the intro to bash and beautiful soup to start, and they will be going through and flagging additional ones that appeal to them. Is there a sense of timeline on when the editing windows would open?

[jerielizabeth]

Reviving this conversation. It sounds like inviting improvements to lessons via pull requests is of general interest, and I like the idea of starting with the bash and beautiful soup lessons as we are both authors and editors of those (test the waters before throwing others in and all that.)

What about making a go of this during the spring 2017 semester? I am willing to take lead on the effort.

[fredgibbs]

Just a quick addition on a related note: I'm going to be teaching grad and undergrad digital history courses next term, and hope to facilitate some new lessons, but probably more activity will be directed at improving certain lessons (not sure which ones we'll engage with most at the moment). Perhaps this is an issue for larger discussion on the next call, but happy to banter about it here in the meantime. Just want to make sure we can optimize our various efforts.

[jerielizabeth]

So, taking lead on this…

It seems from the conversation that we need to have three things in places process-wise for this to be productive and beneficial to us and to those who are interested in improving lessons:

• a set of lessons selected as a test case
• instructions about how improvements can be submitted (issues; pull requests)
• way of acknowledging contributions

Looking back on the conversation, @ianmilligan1 volunteered the Bash lesson and I volunteered Beautiful Soup. Are there any other lessons we should experiment with?

I can draft up a blog post outline goals and how to submit contributions.

For the last one, it sounds like it is not too hard technically to pull in a list of people who have contributed to lesson. But we need some editorial consensus about how to acknowledge that work. I like the footer idea, or new second line in the credits section after “Reviewed by”, such as “Contributors include”.

[fredgibbs]

thanks for taking the lead on this, jeri!

2 quick responses to your prerequisites:

i think 2 lessons are good to start with while we work out our process.

working on page layouts now, i think the footer of the lesson is the best place to acknowledge contributors so as to make sure the author, reviewers, and editor(s) get prime billing. we could have everyone at the top of the lesson, but if there are lots of contributors then the lesson would get pushed way down the page. in any case, ’m not sure we necessarily need to pull them in automatically, unless we find we’re spending too much time making updates to pages; that also means one less barrier to implementing this.

-- Fred Gibbs History Department University of New Mexico @fredgibbs https://twitter.com/fredgibbs || fredgibbs.net http://fredgibbs.net/

On Feb 1, 2017, at 5:31 PM, Jeri Elizabeth notifications@github.com wrote:

So, taking lead on this…

It seems from the conversation that we need to have three things in places process-wise for this to be productive and beneficial to us and to those who are interested in improving lessons:

a set of lessons selected as a test case instructions about how improvements can be submitted (issues; pull requests) way of acknowledging contributions Looking back on the conversation, @ianmilligan1 https://github.com/ianmilligan1 volunteered the Bash lesson and I volunteered Beautiful Soup. Are there any other lessons we should experiment with?

I can draft up a blog post outline goals and how to submit contributions.

For the last one, it sounds like it is not too hard technically to pull in a list of people who have contributed to lesson. But we need some editorial consensus about how to acknowledge that work. I like the footer idea, or new second line in the credits section after “Reviewed by”, such as “Contributors include”.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/programminghistorian/jekyll/issues/304#issuecomment-276804558, or mute the thread https://github.com/notifications/unsubscribe-auth/AAfdeJVkoR9PruAxs6BlLwmlArLOM4_Jks5rYQfXgaJpZM4KjkUD.

[jerielizabeth]

I am relinquishing control of this issue as I step back for the dissertation.

[mdlincoln]

Indeed! I think I'm going to close this now that it's been picked up by #579