Links, citations, and other references: policy needed?

[karenword]

We have some inconsistencies with the ways that we refer to external resources in this curriculum, and I would like to consider a more systematic approach. We currently have an issue requesting an annotated bibliography (#1137) as well as issues suggesting links or resources (#1222 , #556). This is a broader issue to address a comprehensive strategy for referencing.

In reviewing the curriculum for update, I have noted that certain areas are densely populated with external links, while these are relatively sparse elsewhere. We also have a (little used) Reference page. The books and papers cited there are not directly linked to or from relevant points in our curriculum. Each entry also includes a hyperlink either to a WorldCat entry, a pdf stored in our repository, or a doi or journal site.

Hyperlinks to external websites create a unique maintenance challenge in that we do not have control over content that may change. The status quo, in which web links proceed directly from our lesson text while other reference types do not, prioritizes attention to web content over the arguably more robust/peer reviewed material in References.

My inclination is to reduce the total number of direct hyperlinks from our text. We (maintainers) have briefly discussed potentially directing all links first to a bibliography/references page in the future, where those seeking more context can find everything (websites as well as books and papers) in one place. This endnote-style approach may be irritating, however, and presents its own maintenance challenges.

I have a sense that there are a few folks in our community (hello, librarians!) who have far more experience thinking about these things. And anyone may have an opinion on the number of in-text links and whether they continue to lead directly to external sources (or anything else for that matter!). Please comment if you have relevant thoughts to share!

[Denubis]

Some random notes:

1. We should probably make sure external links link through archive.org or perma.cc (assuming an institutional membership from... someone...)
2. I think I made some automatic bibliography stuff in the past linking from zotero -- so we absolutely have the infrastructure for it
3. Github pages can now, with some elbow-joggling support https://github.com/inukshuk/jekyll-scholar. Barring that, I can fairly easily implement a citeproc-js hook in our style to support proper bibliographies.

[brownsarahm]

I think we need to wait on any implementation on this until we get the new style.

[brownsarahm]

#1502 reminded me of this issue and now is the time to consider this with the workbench. That said, I'm going to invite @zkamvar to chime in if there are any relevant workbench features that are not documented that might pertain to this.

[karenword]

I wonder, with the glossary now a featured element, if we might consider including reference links there?

[zkamvar]

Thank you for reminding me of this, @brownsarahm!

With the workbench, now that we are using Pandoc, we get to take advantage of Pandoc's citation capabilities, for which I would need to wire up the right arguments to pandoc and make sure the output makes sense (for the curious, the specifications we pass to pandoc are in the R/render_html.R file)

The only wrinkle would be how exactly to specify a bibliography in a way that satisfies the following conditions:

1. Adding a citation should be easy (at most two steps), it should not require endless fiddling with formatting
2. The lesson can still be rendered offline with the bibliography

The solution for this is to have a bibliography.bib file in the lesson (likely specified by bibliography: 'episodes/bibliography.bib' in the config) and then take advantage of RStudio's citation integrations with Zotero to allow people to add citations from the shared Zotero library.

One of the challenges is that, if we are relying on the shared Zotero library, it becomes more difficult to add citations via GitHub's web interface as you would need to add the bibtex for the citation first and then add the inline citation. The reason for this is that the Zotero integration is via RStudio and is a convenience feature that automates the process and it requires a locally installed Zotero OR an internet connection. R, pandoc, and The Workbench do not know anything about it.

[ndporter]

I am not a librarian (though I have been mistaken for one since that's where I work) and definitely don't have the background to comment on Zotero/RStudio/Pandoc/etc integration. That said, I agree that having citations, possibly with copies linked in our repo (when licensing allows) and external links (but only to permalinks/dois/archives) otherwise when reasonable.

Also, we have an institutional membership to perma.cc at Virginia Tech that I believe could be used to support this if need be.

But in either case, this is probably best left for after the instructor notes drive has had some time to settle, since it may require similar levels of collaboration, unless we put a significant burden on the core team. Honestly, I think having some kind of "drive" quarterly or so is not a bad idea in terms of encouraging learners, new instructor trainees, and current instructors and trainers to engage in an ongoing way.

[brownsarahm]

👀 the idea of quarterly reference drives is intriguing. I have missed several trainer meetings (I miss them!! but my teaching scheudle blocked me) but more ways to engage asychronously would be good and drives can be a good sort of semi-synchronous activity.