Setting standards for referencing external non-web materials

[bernhold]

Many articles on the site will naturally refer to objects other than web pages, for example technical papers or reports, books, etc.

As part of defining the detailed editorial process for the site, we should try to standardize how we present such items, and how they are linked.

For example, we have an article on Feathers's book on Legacy Software. What information should we include in the article to make it easy for a reader to unambiguously and quickly locate the item? Quick thoughts:

• For technical papers and reports, a DOI is often available as a unique identifier. If we have a DOI, how much additional information do we need to provide? It would mostly be for human convenience, I think. Maybe title+authors+DOI suffices? Maybe we want the full bibliographic citation within the article? Presumably we should link the DOI to the well-known resolver, https://dx.doi.org?

• For books, the title and author(s) are useful for humans. The ISBN is the official unique identifier. Should these be provided as bare text? Or should we link to something? I have not been able to find a universal resolver for ISBNs like there is for DOIs. But something like worldcat.org is a union catalog and therefore very likely to have it. Then the question is whether there is a way to query the WorldCat database via a URL? An alternative would be a specific bookseller. Amazon.com would be the obvious candidate. The idea has a number of downsides. First, we're de facto endorsing a commercial entity. Second, Amazon may or may not carry any given publication. Third, Amazon does not operate in all countries, so an Amazon link may or may not be useful to a given reader. On the other hand, if there's an Amazon page for the publication, it would give the reader additional details to work with that we wouldn't have to provide.

• For serials (e.g. journals) there are ISSNs. To the extent that we're pointing places to publish software, for example, the ISSN is probably the unique identifier. I don't know about resolvers or such.

[bernhold]

For the record, the DOI organization provides something called ISBN-A (actionable ISBN) which is a reformatting of an ISBN into a format compatible with DOIs.

For example, Legacy Code is ISBN: 978-0131177055 which is ISBN-A: 10.978.013/1177055, which you can (attempt to) resolve through the DOI system with the URL https://dx.doi.org/10.978.013/1177055.

Unfortunately...

• Knowing the ISBN is not sufficient to construct the ISBN-A. The ISBN starts with "group" and "publisher" codes, which have variable length (to get a sense of it, see https://en.wikipedia.org/wiki/List_of_group-0_ISBN_publisher_codes). And in the ISBN-A, the group and publisher code go before the "/" and the rest of the number go after. So there is no simple regex to translate.
• The publisher has to register the ISBN-A with the DOI system in order for it to resolve. The ISBN-A for Legacy Code has not been registered. So even though we can (with extra work) construct the ISBN-A, there's a good chance it won't be useful.

[bernhold]

Turns out, WorldCat can be searched pretty easily: http://worldcat.org/ISBN/978-0131177055

Similarly for ISSNs: http://worldcat.org/ISSN/2475-9066

What you get from WorldCat is a list of libraries that hold the item in question. So if nobody holds the item, you'll get WorldCat's version of a 404 page. WorldCat is not a registry or a resolver, so there are no guarantees that every legitimate publication will appear here. But it is the union of a sizable number of library catalogs, so I imagine coverage would be pretty good.

The primary value I see in linking to something like WorldCat is that is can be treated as an authoritative source for all of the details someone might want about the item, either in order to purchase it or in order to reference it.

The WorldCat page for Legacy Code does have a "Get a Copy" section at the top right that includes to several bookselllers (in this case Abe Books, Amazon, and Barnes & Noble) as well as to the Amazon Kindle ebook version. I assume these are sponsored links, though they're not labeled as such. But at least there are multiple options. And we wouldn't be directly linking to a seller.

[bernhold]

Okay, I need to stop playing with Google. But here's another ISBN search site I found, in the form of a query for Legacy Code: https://isbnsearch.org/isbn/9780131177055.

It gives basic bibliographic information and lots of links to sellers for new, used, or rental versions of the book.

The site itself is very bare-bones and does not provide information as to who operates it, its data sources, or anything like that.

[markcmiller86]

I have yet to read all of these comments but wanted to mention that the reference stuff you see going on in the recent blog post about Apollo Guidanc Computer or in the script that supports it, you aren't necessarily seeing demonstrated there the final implementation. For example, to get the AGC article live by deadline, I didn't have a chance to fill in true bibliographic data for all the references used in that article. I plan on doing that and when I do, we'll update that live post with it. The script and instructions however, do support capturing full bibliographic details.

[markcmiller86]

Many articles on the site will naturally refer to objects other than web pages, for example technical papers or reports, books, etc.

As part of defining the detailed editorial process for the site, we should try to standardize how we present such items, and how they are linked.

I think it makes sense to standardize even web based links. Why? As a hedge against link rot. In fact, the work I started with @curfman and @bsswimagery for wikipedia-like references in, for example, the AGC blog post is aimed at this kind of standardization; a dual-purpose goal being that we can link to on-line materials as they are available now but also provide full bibilographic information for them to improve reader's ability to re-find the material again later should the link itself rot away.

That approach, which I document here, results in a nice, bi-level linking strategy for references; the first level takes the reader, on-page from a footnote to the item it represents in the reference list on the same page. The item in the reference list (should) contain full bibliographic data for the reference as well as the current best off-page link to an online instance of it.

Now, the details about what constitutes standardization of the bibliographic data are certainly not proposed as part of what I describe here. So, that definitly needs further work. But, I hope the authoring style and link mechanics we have developed can be made to fit with the broader goals here.

[bernhold]

I completely agree with @markcmiller86's comments. Links will be more prevalent than anything else, and they're even easier to get wrong and be susceptible to rot.

I didn't include links in this thread because I think they deserve their own thread. I haven't had time to start it yet. But for the record, I remember some recent discussion (maybe in email) about linking practices and a guide that someone suggested which might serve as a starting point. So when I have a chance to do the archaeology, I'll post an issue for that.

[bernhold]

I think https://isbndb.com may be useful for ISBNs. It just provides title/author and other associated ISBNs.

[bernhold]

@rinkug We've never really discussed this as a group, and Mark is the only one who's weighed in online. I don't think this should be closed until we've actually had a discussion.