Last year we were excited to introduce some important behind-the-scenes infrastructure changes 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:
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, now public for all our community to see. (Spanish version here)
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 tutorial.)
We rely heavily on our community to alert us to problems in our lessons, so please contact us 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, as well as the pull request where we refined the wording of the text.
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.
About the author
Matthew Lincoln is the digital humanities developer at Carnegie Mellon University, and an art historian of early modern Europe.
