Skip to content
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

Lesson archiving policy discussion #536

Closed
acrymble opened this issue Jul 26, 2017 · 19 comments

Comments

Projects
None yet
5 participants
@acrymble
Copy link
Contributor

commented Jul 26, 2017

Arising from our July 2017 editorial call, we need to come up with a policy for deprecation that we can justify and all stick to (see #498)

@mdlincoln

This comment has been minimized.

Copy link
Member

commented Jul 27, 2017

A practical (if somewhat laissez-faire) approach that we are essentially using now is:

  1. A lesson has become so out of date that we receive complaints about it AND
  2. Issues are not fixable by correcting one or two URLs, but instead demand systemic changes to text, code, and/or figures such that someone would need to walk through the entire lesson step-by-step to test AND
  3. After opening a ticket to discuss between editors, we decide that there is no bandwidth to revise the lesson

then we deprecate.

If we decide to constitute some continuing review subcommittee (which it doesn't seem like we presently have the bandwidth for, but perhaps in the future...), then lesson bug reports might come internally in addition to externally.

@mdlincoln

This comment has been minimized.

Copy link
Member

commented Jul 27, 2017

One gray area that I can think of after re-reading #393 - there will be cases where earlier versions of software are still available (Mallet 0.7 vs. Mallet 0.8; python 2 vs python 3) and the lesson still works just fine with them. So a minor change in download url, or an extra warning about use of an older version, could be enough to keep the lesson from being deprecated.

If, of course, earlier versions and their dependences are particularly difficult to install - which might be the case in #393 - then this option won't be available.

@acrymble

This comment has been minimized.

Copy link
Contributor Author

commented Jul 27, 2017

This ties with @alsalin 's advice in #534 that we should be foregrounding dependencies in the metadata. It's one thing for our advice not to be the most up to date, and another to give bad advice that leads scholars down a wrong path.

@ianmilligan1

This comment has been minimized.

Copy link
Contributor

commented Jul 27, 2017

The trick in #393 is that while 0.7 is downloadable, people often come to our site after downloading 0.8. We are the de facto manual for a lot of folks for MALLET.

@mdlincoln

This comment has been minimized.

Copy link
Member

commented Jul 27, 2017

Combined with the dependencies advice, are we missing anything else in this policy?

@acrymble

This comment has been minimized.

Copy link
Contributor Author

commented Jul 27, 2017

Maybe who gets to make the decision. And to what degree we want to avoid doing this?

@mdlincoln

This comment has been minimized.

Copy link
Member

commented Jul 27, 2017

A ticket is issued, we discuss as a group, we decide. I believe authors should be notified if possible (and we should definitely publish this policy in the submission guidelines) but it's our journal and our decision how to organize and present.

Degree is going to be enforced by our editorial bandwidth. If it is beyond our abilities and will to do something about it within a reasonable timeline after a breaking issue is identified, we have to default to deprecation.

Thoughts?

@acrymble

This comment has been minimized.

Copy link
Contributor Author

commented Jul 27, 2017

@mdlincoln It's probably more socially awkward than that.

I suspect our team members won't feel equally comfortable opening those tickets. Especially if it was written or edited by someone else on the team. Lessons edited by emeritus members might find themselves without defenders. I don't think this is as objective as it might seem.

@mdlincoln

This comment has been minimized.

Copy link
Member

commented Jul 27, 2017

You're right, it's absolutely not objective - hence requiring a discussion specific to the context of each lesson, rather than a blanket "if no fix made within 60 days, lesson deprecated" policy. I'd never advocate for the latter.

Practically speaking, though, what additional policy language would be good to record internally & externally (beyond what we've assembled so far) in order to address that concern?

@drjwbaker

This comment has been minimized.

Copy link
Member

commented Jul 27, 2017

Chiming in from the outside (because I'm really intrigued how you might handle this and am therefore following along..):

  1. Using less software specific language to describe all this might be useful: how many historians use/understand "deprecate" in the way you mean here?
  2. All papers age but none are officially 'deprecated' by journals. Making sure authors know that deprecation doesn't mean that you are criticizing their lesson is important.
  3. In order to smooth the credit angle, can the deprecation process be combined with a small celebration of the success of a lesson in its active lifetime? A foregrounding of web traffic stats, referrals in and out, number of revisions, number of translations - for example - in the header of the public page of the now deprecated lesson.
@mdlincoln

This comment has been minimized.

Copy link
Member

commented Jul 27, 2017

@drjwbaker these are really excellent points! I especially like 3 - just because we're "retiring" (?) a lesson doesn't mean it was a failure - the very fact that people would raise alarms about it being out of date would suggest that it's a valued resource.

@fredgibbs

This comment has been minimized.

Copy link
Contributor

commented Jul 27, 2017

maybe instead of deprecate we should archive. we could also have an "archives" button or something on the lessons index page to improve visibility of those lessons and explain the what and why of our archives (and maybe invite/encourage people to create a derivative lesson with more recent software versions).

@drjwbaker

This comment has been minimized.

Copy link
Member

commented Jul 28, 2017

"the very fact that people would raise alarms about it being out of date would suggest that it's a valued resource."

Quite.

@acrymble

This comment has been minimized.

Copy link
Contributor Author

commented Jul 28, 2017

I think we'll need to distinguish between:

  1. (technical) You can't actually do the lesson anymore because the technology doesn't exist / is so difficult to get together that it's unrealistic to expect an intelligent human to do so.
  2. (social) There's a better way that you could do this task now.

The first is fairly objective, and in my view is what we're after here. The second type, I'd rather we left alone unless extraordinary circumstances arise, or we'll never be able to stop revising things.

@mdlincoln

This comment has been minimized.

Copy link
Member

commented Jul 30, 2017

@acrymble That's a useful distinction. I agree with you that 1 is a good candidate for "archiving" (which I definitely like better as a term!). 2 is not enough to archive - although I think it is something worth of consideration by peer reviewers re: #534

As far as explaining this policy publicly: right now, we have a banner that appears on lessons that have been deprecated/archived. I think, in addition to the brief in-place message, it is worth devoting a dedicated page to explaining our archiving policy. This could be a sub-page alongside our author/editor/reviewer guidelines. There we can explain:

  1. What small repairs will be made
  2. When we will consider a lesson for archiving
  3. What happens to a lesson when it is archived (still published at the original URL, but no longer listed on the main lessons page)
  4. What happens when someone submits a derivative lesson that makes major updates to an archived lesson

mdlincoln added a commit that referenced this issue Aug 1, 2017

link to lesson deprecation/archiving issue #536
It's worth drawing attention to this discussion

@mdlincoln mdlincoln self-assigned this Aug 24, 2017

@mdlincoln

This comment has been minimized.

Copy link
Member

commented Aug 24, 2017

From 2017-08-24 meeting: I will take point on compiling a draft page with our archiving policy, and then invite comment from our whole team

@mdlincoln mdlincoln referenced this issue Aug 28, 2017

Closed

Twitter Bot and Deprecated Lessons #514

3 of 3 tasks complete

@walshbr walshbr referenced this issue Sep 26, 2017

Closed

Editorial Meeting Agenda - 9/28/17 #596

0 of 6 tasks complete
@mdlincoln

This comment has been minimized.

Copy link
Member

commented Sep 28, 2017

The dog ate my homework! Sorry, I dropped the ball on this. I will submit some text here by 2017-10-15.

@mdlincoln mdlincoln changed the title Deprecation policy discussion Lesson archiving policy discussion Sep 28, 2017

@mdlincoln mdlincoln referenced this issue Sep 29, 2017

Merged

Lesson retirement policy #612

13 of 13 tasks complete
@mdlincoln

This comment has been minimized.

Copy link
Member

commented Sep 29, 2017

Any further comments, please add in the review thread for #612

@mdlincoln

This comment has been minimized.

Copy link
Member

commented Feb 15, 2018

Closed by #612

@mdlincoln mdlincoln closed this Feb 15, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.