Skip to content

Commit

Permalink
Blog post on retirement policy
Browse files Browse the repository at this point in the history
* draft post on retirement policy

* don't try to use PH url

* Remove horizontal rule
  • Loading branch information
mdlincoln authored Feb 19, 2018
1 parent 836b5bc commit f75473e
Showing 1 changed file with 40 additions and 0 deletions.
40 changes: 40 additions & 0 deletions _posts/2018-02-15-retirement-and-sustainability-policies.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
title: Lesson Sustainability and Retirement Policies
authors:
- Matthew Lincoln
layout: post
categories: posts
---

Last year we were excited to [introduce some important behind-the-scenes infrastructure changes](/posts/infrastructure-at-ph) that would help catch broken links and metadata errors across all of the pages and lessons in _The Programming Historian_.
However, no set of technical solutions can address every sustainability problem faced by lessons about the fast-developing world of software.

That is why, for the past few months, _The Programming Historian_ editorial team has been working to codify sustainability guidelines for our authors, editors, and peer reviewers to consult as new lessons are developed.
These include suggestions like favoring tutorials on well-supported software and tools, being mindful of software versions and version-specific language, and favoring data examples that are hosted directly on our site.
We hope that these new guidelines will result in easier-to-use, more long-lived lessons:

- [Author Guidelines for Writing Sustainably](/author-guidelines#write-sustainably)

- [Reviewer Guidelines for Assessing Lesson Sustainability](/reviewer-guidelines#sustainability)

- [Editor Guidelines for Fostering Lesson Sustainability](/editor-guidelines#c-sustainability-review)

However, we acknowledge that even the most well-thought-out sustainability guidelines can't guarantee that a lesson will work in perpetuity.
Major changes in software and community practices (for example, the switch from Python 2 to Python 3) can affect our lessons to the extent that they would need to be entirely rewritten to maintain their usefulness.
Over time, our team had developed _ad hoc_ processes for how to deal with these issues, but we felt it was time to codify those processes, and to do so publicly.

We settled on a dedicated [Lesson Retirement Policy](/lesson-retirement-policy), now public for all our community to see. ([Spanish version here](/es/politica-retirada-lecciones))

To summarize: _we do not retire lessons lightly_.
Our policy lays out reasons why we may consider a lesson for retirement, and reasonable steps that we may take, including minor edits to published content, to forestall the need to retire it.
When we do elect to retire a lesson, we will make those reasons transparent to our entire community.
We will ensure that the original text of the lesson is preserved on our site rather than being erased, and that old links to it will always work.
We will also make clear to our readers which lessons are considered up to date, and which have been retired, and thus may no longer work with current software. (You may see an example of what a retired lesson page looks like with our [Counting Frequencies from Zotero Items](/lessons/retired/counting-frequencies-from-zotero-items) tutorial.)

We rely heavily on our community to alert us to problems in our lessons, so please [contact us](/feedback) if one of your favorite lessons is no longer working!

As with all big changes at _Programming Historian_, these new policies are the result of a group effort involving intense discussion and debate within our editorial team.
We also want to thank the broader community for your contributions and suggestions during this long process, which ranged from broad suggestions to small, but crucial changes to site layout and design around retired lessons.
For anyone interested in how this conversation developed, we recommend reading the [GitHub issue where we developed our guiding sustainability principles](https://github.com/programminghistorian/jekyll/issues/536), as well as the [pull request where we refined the wording of the text.](https://github.com/programminghistorian/jekyll/pull/612)

Finally, we owe special thanks to Antonio Rojas Castro, who tirelessly translated this considerable amount of new text into Spanish, and to the rest of the Spanish team for their careful reviews.

0 comments on commit f75473e

Please sign in to comment.