Rename tool "Citations" to "References"

[nsoranzo]

and former "References" (xrefs) to "External links".

Fix #19740 .

How to test the changes?

(Select all options that apply)

• I've included appropriate automated tests.
• This is a refactoring of components with existing test coverage.
• Instructions for manual testing are as follows:
  1. [add testing steps and prerequisites here if you didn't write automated tests covering all your changes]

License

• I agree to license these and all my past contributions to the core galaxy codebase under the MIT license.

[nsoranzo]

Test failures unrelated.

[bernt-matthias]

Do we have references for workflows?

[nsoranzo]

Do we have references for workflows?

Not per se, as far as I know.

[mvdbeek]

I guess the obvious caveat is that tools are not academic texts. As such I find citations more appropriate, because it also implies that you're supposed to cite the citations. I wouldn't 👎 but I don't like the change.

[jmchilton]

I read the article and I appreciate the clarification as a personal thing. I feel like I've learned some things and I will try to be more precise with my language going forward.

I guess the obvious caveat is that tools are not academic texts. As such I find citations more appropriate, because it also implies that you're supposed to cite the citations. I wouldn't 👎 but I don't like the change.

I don't find the caveat obvious - I appreciate you explaining my intuition better than I could.

I think what would convince me this should be changed is if I was convinced there was some cognitive load introduced by this being "wrong" - like what the citation was in the context was confusing a group of researchers using Galaxy. I can imagine there is some cognitive load that is introduced on developers when the tool XML does not align with the language in the UI and that could be okay and worth the cost if it was helping user. If we are introducing that cost and it is just for "correctness" though... that is just never going to align with my values. I have been having conversations with @bgruening this week and I have had conversations with @martenson in the past about changing terms like "object store" and "file source" in the UI because those are too technical - I really appreciate that they made the case that these things were confusing and in fact @bgruening even brought data to the discussion.

So I am a -0 as it stands - I have my opinion but I understand it is completely biased by being a native English speaker and not a traditional academic and dyslexic and having an easier time seeing the implications for developers than users. I don't claim to represent users in this discussion.

[mvdbeek]

I don't find the caveat obvious

Sorry, that was in relation to the article, which says Both are associated with academic texts and are pointers to sources of information.. I didn't mean that the distinction is obvious, it isn't.

[nsoranzo]

Thanks both for the comments!

I guess the obvious caveat is that tools are not academic texts. As such I find citations more appropriate, because it also implies that you're supposed to cite the citations. I wouldn't 👎 but I don't like the change.

It's true that tools are not academic publications, but "References" is used consistently in journal articles:

https://www.nature.com/articles/s44185-024-00054-6#Bib1
https://www.science.org/doi/10.1126/science.adl5414#bibliography
https://www.thelancet.com/journals/lancet/article/PIIS0140-6736(24)02813-7/fulltext#references
https://academic.oup.com/bioinformatics/article/30/19/2816/2422231#401750704

and in many scientific databases, e.g.:

https://www.genenames.org/data/gene-symbol-report/#!/hgnc_id/HGNC:11998
https://reactome.org/PathwayBrowser/#/R-HSA-388841
https://www.wikipathways.org/pathways/WP5518.html
https://www.ncbi.nlm.nih.gov/protein/NP_000198.1
https://rfam.org/family/RF00162
https://www.lipidmaps.org/databases/lmsd/LMFA01010015
https://flybase.org/reports/FBgn0035542

There are other databases that use "Publications", "Bibliography" or "Literature" for this, but I haven't found one that uses "Citations".

On the other hand, "Citation" is clearly defined in Wikipedia as "an abbreviated alphanumeric expression embedded in the body of an intellectual work that denotes an entry in the bibliographic references section of the work for the purpose of acknowledging the relevance of the works of others to the topic of discussion at the spot where the citation appears."

Also "citation" is a well known term to researchers because of how a journal impact factor is calculated: https://en.wikipedia.org/wiki/Impact_factor#Calculation , something every scientist is aware of.

We can make it clear that we encourage the user to cite the references with a section subtitle "Please cite the following:", but take into account that often they are also actual references for the (help) text we use in the tool, which is usually copy/pasted from the underlying tool, so the Galaxy author need to mention them.

[bgruening]

I like the "external link" change. This fits better IMHO.

We can make it clear that we encourage the user to cite the references with a section subtitle "Please cite the following:", but take into account that often they are also actual references for the (help) text we use in the tool, which is usually copy/pasted from the underlying tool, so the Galaxy author need to mention them.

Isn't that problematic for the "extract all citations for my history feature"? We want only things in there that people need to cite when they write a paper isn't it? So the wording should discourage putting in readthedocs pages in the reference/citations section.