-
Notifications
You must be signed in to change notification settings - Fork 229
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Sustainability Strategy for lessons #534
Comments
#499 draft blogpost had relevant text on this. But given Anandi's expertise, perhaps we should wait and do it right. |
I like the info in #499, but there are some things we might want to consider given the conversation during today's meeting: Making the following explicit in the metadata at the top of each article. In my random survey, articles have this information at different spots in their introductions, which vary greatly.
Sustainability ideas/questions
That's all I have for now! |
One note that I think @JMParr raised in the meeting today by skype message was that a reviewer for an R lesson submission said they'd require that the lesson be resubmitted using currently-maintained R packages. I think this is a great example of peer review working as intended, where a specialist in that particular language/software brings subject-specific sustainability issues to the attention of the author & editor. Could we add a bullet point to the reviewer guidelines asking them (if they have the knowledge of the particular software environment) to evaluate how up-to-date the methodology and tooling is? We already ask them to consider the sustainability of external datasets. |
This sounds like a good bullet point to the reviewer guidelines. Certainly,
we want to encourage the peer reviewers to point out when there are newer
versions of software packages.
…On Wed, Jul 26, 2017 at 8:16 PM, Matthew Lincoln ***@***.***> wrote:
One note that I think @JMParr <https://github.com/jmparr> raised in the
meeting today by skype message was that a reviewer for an R lesson
submission said they'd require that the lesson be resubmitted using
currently-maintained R packages. I think this is a great example of peer
review *working as intended*, where a specialist in that particular
language/software brings subject-specific issues to the attention of the
author & editor.
Could we add a bullet point to the reviewer guidelines asking them (if
they have the knowledge of the particular software environment) to evaluate
how up-to-date the methodology and tooling is? We already ask them to
consider the sustainability of external datasets.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#534 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AVruWzTJCJhNuL9_LzsUs7oxtljPMFP8ks5sR9bhgaJpZM4OkMBO>
.
|
One of our ongoing sustainability strategies has been to encourage Wikipedia links for technical terminology and jargon. I think that's worked really well. |
Following on the conversation in #596 - @alsalin I'm wondering if there are any other particular things that you (or anyone else) see that should be done for the backlog of lessons? Largely was thinking about this in the context of making sure that we're hosting all of our own assets, which @mdlincoln and others just did for several older lessons. @alsalin were you suggesting a more thorough sustainability review, or just working towards more proactive sustainability processes for the future. I'm all for either one, but a review of past lessons seems like a much more substantial investment of time. I also think it would be helpful to frame some sustainability guidelines, for all of those communities but particularly reviewers, in terms of concrete things that they can be checked. Things like: what sort of sites does the lesson link to, how many external pieces of software are discussed, etc. Perhaps obvious, but I'm thinking of people like me, who recognize that sustainability is important in the abstract but am less clear about hard and fast rules I should watch out for. |
@walshbr I've been following the self-hosting of assets and it's a fabulous idea. I hadn't really considered an audit of previous lessons because, as you mentioned, it would be a substantial investment. That's not to say if someone sees an issue in an older article that we shouldn't address it. I was framing my suggestions for future lessons and was considering language for author, editor, and reviewer guidelines. There would be kind of a suggested checklist but then also some general guidelines to follow. Mostly my notes need to be in complete sentences, so I'll be posting some ideas soon. |
Some specific problems that show up in links:
|
@alsalin I think it'll be important to cross-reference the lesson retirement policy with these sustainability guidelines - so I'd like them to go under the same PR #612 (not to mention, it'll help unify all the changes, thus making the Spanish team's job easier.) That means we'll need to get your suggested edits before closing out the lesson retirement policy changes. Do you have a realistic timeline for submitting these for everyone to look at? |
@mdlincoln I hope to have some drafts up in the next day or so. apologies for the delay, but I've been a bit under the weather the last week or so. |
No rush @alsalin - just need a realistic timeline, that's all. |
Hi all, here are some suggestions on verbage for sustainability. These are merely suggestions for placement and content. I've tried to summarize suggestions from a few different places, but please review for accuracy and appropriateness. Rather than repeat everything in every section, I tried to word the guidelines for each audience as best as I could. Question: would it be helpful in any of these sections to call out the retirement policy? Editor GuidelinesUnder Open Peer Review Under Technical Processes of Review
Reviewer GuidelinesUnder What to Comment On
Author GuidelinesUnder Proposal Guidelines (taken from #499) Under Writing a New Lesson
|
This is great. I thin we can add in new advice as and when we come across problems. |
This is really good, thanks @alsalin! My only hesitation is the verbiage around:
I've always thought that this one of the Programming Historian's strengths: being able to take overall methodological concepts (which are important), but then assuming a low-level of technical knowledge and really breaking things down for users. Reminding them to double-click an archive file to open it, or to change the directory into the one that they just downloaded, or that x or y is hidden behind a menu item in the As tutorials, especially beginner-level ones, I think we should be OK for people giving very detailed instructions. |
Looks really great to me. And just to underscore what @ianmilligan1 is saying - I had the same thoughts. In general, when I've been involved, those sort of additions have been based on extended back and forth with reviewers/authors who can't figure out how to do something. Ie - "It says click this to download, but it's not downloading. It's still not downloading." etc. And if something requires that sort of discussion behind the scenes for people who we're helping through the process, it seems worth documenting for a general readership. To some extent that's a question of basic web/digital literacy, but I'd rather err on the side of readability in that case. Maybe Ian is right in that it's a question of determining the difficulty level that the tutorial is pitched at. Personally I'm inclined to err towards detailed instructions in most cases, but I recognize that isn't necessarily always called for given the sustainability discussion and the difficulty rating system we've been developing. |
@ianmilligan1 @walshbr excellent points - I think we can certainly add language that the reviewers and editors should be aware of the level that the lesson is geared towards when making these determinations. also, it may be possible, if we implement something like hypothes.is in the future, for some of these details to be annotated and then updated by our readership. in the meantime, I think it will have to be up to the editors/reviewers to determine how much specificity is too much given the audience for the lesson. |
Good points all. Giving editors something to think about is different from prohibiting screenshots/instructions, etc. So if we're thinking about 'guidelines' then I think it's worth reminding editors and reviewers that certain decisions may have a future sustainability impact. |
🥇 these are really great @alsalin - as for where to reference the retirement policy, I'd link to it in the author guidelines at the end of the Write Sustainably section, e.g.
Please strengthen one statement in the author guidelines:
This aligns the author guidelines with the editor guidelines, which correctly state that data should almost always be hosted on our site. |
@mdlincoln do we want to wait until #617 discussion to push the edits? i'm fine with either, but i wasn't sure since it seemed like sustainability was on the meeting agenda. |
We're not merging the changes yet, just adding them to the PR so that people can preview them as they would appear on the published site - something I think will help anchor conversation. Plus, if they're committed as changes in a PR, then we can do inline commenting, so it's much easier to have concrete discussions. |
@mdlincoln great! i will make my attempts probably tomorrow and hopefully not destroy everything :) |
@mdlincoln I gave it the ol' college try. please verify that I didn't ruin PR #612 ;) |
You didn't. All further conversation about this issue should now take place on #612 |
Closed by #612 |
Coming from #498, we need to develop a strategy for how authors can write in a way that minimises the need for changes in future, and for readers to understand what to expect.
The text was updated successfully, but these errors were encountered: