Credits: a new project related to citations, references and attribution

[rlanzafame]

Over the last few months we've updated the Manual with guidance on copyright and licenses and how to properly refer to the work of others on a Credits page. We've also been working on versioning and APA references. This new project is called Credits because it is about improving the process for defining where material comes from and making sure that this is clear and transparent in a variety of places.

Online books must face a duality in their existence: they can be completely defined by source code, but the primary purpose of their interaction is the rendered book (website). When sharing with open licenses like CC BY we need to make it easy for others to properly refer to the source material, as well as keep track where it came from. As TeachBooks, we would like to help make this as easy as possible for others. This means finding a readable and easy approach for defining relevant data, making a few scripts to process data easily, deploying that in a package (teachbooks or sphinx extensions), adding instructions in our manual, setting up a few examples.

The data is "stuff" like author, title, license, etc. It needs to be human-readable, easily ported to bib format or CITATION.cff format, easy to turn into text in a Jupyter Book. Most importantly, we only want to define it once and let the rest happen as automatically as possible.

Here is a draft requirements list:

1. data defined in one place
2. data is human-readable --> _credits.yml
3. allow for different files within a repository to be credited differently (e.g., chapters written by various authors, with an editor for the book)
4. data file is capable of mapping data to specific local files or directories (relative path) or those at a remote URL
5. easy to map data from the _credits.yml to other formats like bib and CITATION.cff with a simple parser
6. ideally the information can be used in other platforms as well (e.g., Zenodo, GitHub, etc); however, a bib reference is prioritized in case decisions must be made
7. allows for new fields to be added and used, as we aren't really sure where we are going with this yet

[rlanzafame]

So why not just use the citation file format? It doesn't seem to allow the flexibility needed to completely capture some book types. For example, the editor-author arrangement where chapters have different authors. This means the repo needs to have a unique citation file for more than one subdirectory. So better to store the data in a separate file, then create the citation file directly for any chapter, as needed, using a simple script.

[rlanzafame]

and while the original description above describes converting to bib or citation, in reality we will probably use cffconvert to go from _credits.yml to cff, then from cff to bib