Code as Heritage

[spapastamkou]

This is the issue of the lesson Code as Heritage submitted to Ranke.2 by Titaÿna Kauffmann @Titayna.
The initial editorial comments were delivered in an in-person meeting with participation of Valérie Schafer who had previously provided feedback to the author. My comments are communicated by email to the author. The lesson is currently under a first revision from the author.

[valschaf]

Why 25 Mns in 1A
Berry, D. at the end: first name missing in references

[valschaf]

Musiani, F., & Schafer, V. (2016). Digital …
—> first names missing

Cross-referencing exercise: To deepen your analysis, look up (at?) these contemporary sources:

Add an actioniable hyperlink at
Visit the CodeCommons initiative by Software Heritage: codecommons.org/

[spapastamkou]

@Titayna I start sending my comments on the revised version of your draft. Thanks again for your work that is very rich. The lesson has many many strong points, mainly its originality and novelty. But I have to insist here on what needs to be reworked in order to now fashion it in a way that it follows the principles of a hands-on lesson for Ranke.2. Below you will find suggestions on how to proceed and we can work together if this is easier and quicker (for example in an in-person work session). I paste some general comments on the overall approach and will post separately comments for each part.

General

Agreed version of the draft lesson

This feedback is based on the file lastly submitted by the author as v2 which I renamed using the slug of the lesson (code-as-heritage.md) and can be found in the folder of drafts: https://github.com/C2DH/ranketwo-submissions/blob/master/lessons/drafts/code-as-heritage.md PLEASE ONLY USE THIS FILE TO MAKE UPDATES ON THE LESSON DIRECTLY - NO NEED TO OPEN PULL REQUEST, THE COMMITS WILL BE INTEGRATED DIRECTLY Me or @frederic-reis can provide further help if necessary.

(The file that we used initially was moved, after the latest merge, in a folder for deprecated files: https://github.com/C2DH/ranketwo-submissions/blob/master/lessons/drafts/deprecated-versions/code-as-heritage.md, and it will be deleted after publication of the lesson. PLEASE DO NOT USE THIS FILE FOR MAKING UPDATES)
GH allows precisely to handle different versions of the same file, so let us stick to the main draft and avoid multiple files, otherwise this will create confusion.

Lesson structure

The revised version of the draft was much longer than the initial draft; some of the titles and subtitles a bit too generic; and the learning objectives numerous with some possible overlaps. I edited directly in order to gain time and show the direction, instead of describing it in detail here. All edits are subject to further revision if necessary. The most important are that I isolated the 2c and transformed it to a separate part under number 3, because otherwise the 2 was too long and difficulet to follow. And the former part 3 naturally transformed to part 4. The learning objectives of part 2 are kept in the .md in comment

You can see these edits in this commit: Updates structure, learning objectives and titles 9056ab8

Learning objectives

It is better to avoid entangling too many learning objectives for each part - a maximum of three is to be defined but one to two are even better. This keeps each part coherent, tight, and easy to follow for the audience. Tip: focus on what is essential and proper to your source and discipline (for ex.: persistent identifiers of digital objects are important to understand - however, this is too peripheral a learning objective for a lesson focussing on a historical source type, as it is part of a more general understanding of metadata). I applied the principle directly in the edits I made, based on your forulated objectives.

References

This is a minor point, in the sense that I will take care of the corrections regarding points 1 & 2; please focus on point 3.

1. Reading/viewing suggestions as section: Reading and viewing suggestions in Ranke.2 are a unique section that follows each part numbered 1, 2 etc, not specifically each subpart such as 1a, 1b etc. In the final version of the lesson, I will group them in the end of each part and put subtitles to distinguish them according to subparts they belong to.
2. Links to publications: We avoid using Google Books links to prefer open access links. Alternatively, if the content is not accessible, we use a DOI or permalink from a library catalog such as worldcat or abes.
3. There are numerous references that are used as when writing scientific articles; it is of course important to anchor the text in the scientific landscape, however, this a lesson, not an article. For this reason, it would be helpful to alleviate the references that are enumerated and focus mainly on these that would be essential and accessible to the readers of the lesson (students or historian whi initiate themselves in analyzing code as historical source. If you

What needs to be done:

• review the references as per point 3 above - Titaÿna
• clean the references to have open links - Sofia - update 18/03/26: the task will be completed after review above
• gather the references in one final section for each 1, 2, 3, and 4 - Sofia

Images and captions

The use of image must have a purpose of demonstration vis-à-vis the main body of text with a bacic caption (title, date, rights of use, provenance). Several images have captions that include both explanations and comments: they end up being too long and eventually distract from the main text. See figures 5, 6, 7, 8, 9, 10 and 11.

• What needs to be done - Titaÿna: refocus on the main text, e.g. integrate the text of the captions in the main body of text, if possible. This may help to judge if the image is really necessary to demonstrate what is in the main text. If the image goes to further details and acts independently (more or less) from the main text, maybe it is possible:
• to use these images in order to build exercises (and make the point that is tackled in the comments)
• to use these images to introduce a subpart in the text, which means the comment of the caption would make a point in the main text
  The idea is to make the relation between the main text of the lesson and the images more interactive, instead of what I see as small subparts in the text created around the image.

Transversal comments on the approach

1. Open/proprietary code: At a certain point, early in the lesson, it would be good to (very briefly) distinguish what is open and what is proprietary code, even with the sole insertion of hyperlinks and a brief reference on the importance to distinguish. Knowledge of these notions ought to not be taken for granted, especially since the lesson targets beginners, in order to make clear how openness vs copyright conditions access, possibility of analysis, and preservation (for code as cultural text). Once done, this would also make more clear to what preoccupations reverse engineering responds to, that otherwise is mentioned but remains a bit dark in the lesson.

2. Versionning technologies: Notions like versionning, repo, commits etc must be further (but very briefly) explicited or linked to external sources. I did not find a video that would work for non programmers. The most simple, in my eyes, remains the documentation of GitHub https://docs.github.com/fr/get-started/start-your-journey/hello-world that explains very simply, in each part, what is what. Alternatively, I thought that I could create a short, non-tech, tuto explaining git and the connected notions that we can publish separately on Ranke.2 and link to the lesson (we have something like this on Communalytic, related to the lesson on social media, but this is more technical and long than what I have in mind). I could have this ready while the lesson will go under peer review.

3. Hardware: this element is important for both analysis and preservation but rather overlooked in the lesson. For the moment, I invite you to keep this in mind, because it is equally possible to have a discussion on this point during the peer review and get the views from external readers in order to see how this aspect could be integrated in the framework of internal/external criticism.

4. Literacy for analyzing code: Slight contradictions in various parts of the lesson regarding the need to have some or not at all technical knowledge:

• Introduction https://github.com/C2DH/ranketwo-submissions/blob/master/lessons/drafts/code-as-heritage.md#introduction
  "However, understanding code as a historical source does require engaging with its technical dimensions; learners will be guided toward accessible resources to build this foundational knowledge alongside their critical skills. While designed for beginners, some exercises require basic digital navigation skills and familiarity with academic research practices." ==> I believe this is pertinent and well expressed, and should be the guiding thread of the lesson
• Part 2:
  • mentions "new literacy" without further precisions twice in the beginning of part 2 and subpart 2a.
  • in 2a defines 3 levels of interaction between historical analysis and technical understanding. The very first of them (Reading code as cultural text) underlines that no programming expertise is necessary. However, what follow is what seems to me being this new literacy and, more precisely, this is what we could define as data literacy or as skills of historical data management, to mention a few.
    To sum up, what I think is the following:
• the "new literacy" mention has to become more concrete because among other things this is what the contribution of this lesson is about, and also you should valorize indirectly your specific skills for working on such a subject
• the data (and metadata) literacy, which you can name otherwise if you wish, must somehow be mentioned as desired skills to do analysis of code as historical source, because without these, no analysis would be easy, if indeed possible.
  This can be another point to further discuss with the peer reviewers, if you wish.

5. Hands-on: the dimension of a hands-on approach is currently absent or random in the new parts that you added. We need to adress this, especially in parts 3 (Apollo code) and 4 (preservation strategies) to avoid having a text that tends to a lecture or a scientific article. I make suggestions separately but perhaps we should work together on this, if you prefer.

[spapastamkou]

Detailed comments per assignment/sub-assignment

1.a

Problem: This sub-assignment will lack a dimension of hands-on activity as long as it remains descriptive and enumerates .
Suggestion: An idea would be to invite readers to explore one or several examples of code, that can somehow be relevant to historians, as proposed below in a quick example (which you may use or adapt as you wish, or just get inspired from). Such a part can be added in the subassignment in the place that you judge best (in the end or elsewhere).

"Explore below:

• an example of scripts written in R to explore historical data as part of a publication. Check the instructions and outputs and see if you can understand what they tell. These scripts are a technical implementation. In term, they could reflect how research with use of a programming language for analysis of historical data takes place in a particular moment of time.
• an example of scripts conceived to convey a political message after the Russian invasion of Ukraine
• an example of politically localized code LAWM (Latin America World Model

[spapastamkou]

2

Learning objectives: from the 7 enumerated, I kept only the very first one because that one includes all the rest; for the sake of clarity; and because technically the web page of a Ranke.2 lesson cannot display more than 3 at best.

Titles:

• Why not rename the 2: "Reading Code as Historical Source"? This is what it is about in this lesson, no?
• I renamed directly 1a and 1b in an effort to reflect that the a proposes to define a framework of historical method analysis and the b offers concrete examples of application.
• I separated former 2c that now is 3 on its own

Other edits:

• Rephrased the beginning of 2 as follows: "Understanding source code as a specific kind of born-digital source helps us approach it with appropriate analytical tools."
  To focus on code specificity among other born digital sources as well, not only in opposition to traditionnal sources

• Artifact 1 => renamed "Image" to "Document" as the former can be misleading

• Microsoft repo: j'ai fait qqs modifications pour apporter plus de clarté et guider les lecteurs et lectrices dans le GH repo et l'histoire des commits.

2.a

Problem: this subpart is long, with:

• a lot of references in the section "Source criticism and born-digital heritage", that make the text feel more academic than educational
• overlaps between sections "Specificities..." and "Key analytical questions..."
• technical details that are not necessarily known by everyone, and seem unnecessary at the current stage since they are not mobilized in exercices or supported by readings or hyperlinks. For example, in "Specificities...", mentions to GitHub, version control systems, commit, branch.... Knowledge of this stuff should not be taken for granted but as a learning objective of the lesson:-)

Suggestion:

• Reorganize the text: combine the paragraph with the 3 levels of relationship between between historical analysis and technical understanding (currently opening 2a) and the small part that follows under title Source criticism and born-digital heritage into one and use it as short and tight introduction to the 2 (so move them out of 2a). This would involve:
• keep the 3 levels as they are
• ban the title "Source criticism and born-digital heritage" which is much too broad for the lesson
• synthesize radically the part with references + hyperlinks as follows (more or less): "the current state of research in the humanities recognizes code as object of research (please refer to the bibliography provided in the reading/viewing suggestions)" so the references will be moved in the section at the end of 2 and then continue with the part on Marino argument, preferably simplified. If you wish, you can use an extract of Marino (or other bilbiographical reference) to ask a question to the audience in order to provide them with a small exercice, say, in the following part.
• merge the "specificities" and "key analytical questions" in one part, for example in something like: "Specificities of source code as historical source: key analytical questions". These two currently overlap a lot (the former is almost entirely present in the latter) and can be both alleviated and simplified. Technical details can be omitted here, but of conserved, then at least hyperlinks should be provided.
• This merged part that I suggest can be framed in terms of principles or analytical framework for applying source criticism on code (which will follow concretely in 2b).

2.b

Remarks, questions:

• The structure of 2b: Currently 2b is organised as follows: Artifact 1/Exercise Part 1; Artifact 2/ Exercise Part 2. Maybe add in the beginning a short paragraph outlining the exercise and its aims?
• In current exercise 1, points 1 and 4 are relevant to external critique, and points 2 and 3 are relevant to internal critique: I would suggest to make this explicit.
• In beginning of part on artefact 2: snippet, BASIC, (GitHub) can be unknown notions. At least hyperlinks should be inserted and/or short explanations injected in the text (for example, what is BASIC.
• I would suggest to either remove the mention on the fact that Microsoft published the code on GH or otherwise explain what GH is, and what anachronism takes place with the fact the MS deposes the code there. The aim of the exercice is to focus on the dicument, so maybe we should think collectively how to resolve this?

[spapastamkou]

3 (Case study with Apollo code)

I turned this (from formerly 2c) to assignment 3, defined a learning objective by more or less partly reusing formulation on what you had previously as learning objectives in part 2, and added a precision in the title that this is a case study. I did not proceed to further edits.

• Now this part needs to obtain small a, b, c... You can no doubt build them from the current material you have there
• A hands-on approach is necessary in these subparts. Currently, this part offers a lecture but what is needed are small exercices to make the point and pedagogical materials: what do the readers need to consult to gain the knowledge you want to give them? Are there videos you can use? Photos? Margaret Hamilton is mentionned, but there is no explanation why she is important. Perhaps this can be a small exercice in one subpart by providing some instructions? Idem for the rest
• Explain notions such ad timestamp, if used.
• Cut! This part is too long and detailed in discourse, but it lacks hands-on practice.

Overall, I would suggest that you keep this part concise, focus on one or two aspects you wish to highlight, and tie them to the question of code source criticism presented in the part 2. We can exchange orally if you wish, and as suggested above, work together.

[spapastamkou]

##4 Preserving Code

I eliminated two learning objectives: the first (too broad and better served in parts 2 and 3) and fourth (out of the scope of the lesson and relevant to metadata), and I rephrased one of the two remaining to make it more general and less focussed on one institution.

I would suggest to reduce the most possible the development on technical architecture of Software Heritage. These things can change in time and we can anticipate now a potentially broken lesson if in some yars form now something changes from this aspect. Same for the evaluation of the technical features of SH, that we can leave out. I would suggest that the Programming Historian lesson be referenced here (or mentionned and included in the section of reading suggestions).

Resources for learning to code: https://github.com/C2DH/ranketwo-submissions/blob/master/lessons/drafts/code-as-heritage.md#resources-for-learning-to-code
This part goes beyond the scope of the lesson, is voluminous. I recommend to only keep the first part that is relatable to humanists. The rest could be not necessarily relevant to historians and could be very difficult to keep up to date.

[spapastamkou]

Thank you for your attention and I remain available for further precisions, exchanges and common work.