search

the-teachingRSE-project / competencies

The teachingRSE project: "Teaching and Learning Research Software Engineering"
Creative Commons Attribution 4.0 International
27 stars 19 forks source link

Consistency - links and language #159

Closed jcohen02 closed 9 months ago

jcohen02 commented 10 months ago

In doing a full read thorugh of the competencies manuscript, I'm noting a few minor inconsistencies that we should aim to address.

Links/references: We mostly use references to highlight key related/external work or entities. However, in at least one case (e.g. the ENCCS section), I spotted a link embedded into the text - I'm assuming this, and any other such links, should be switched to references?

Language: I'm noticing some minor inconsistencies in the use of Britsh and International/US English. Some of this may be my fault but I also noticed that when I then tried to ensure that I'm using US English spellings, e.g. professionalize as opposed to professionalise, the spell check run tells me that spelling is wrong. Although I see uses of other words such as organization, instead of organisation which the spell check process isn't picking up. I'm happy with whatever approach we choose to take but we should probably aim to ensure we are consistent.

ljgarcia commented 10 months ago

I have seen mostly British, at least in the career path I saw only British (maybe once American). Other consistency issues: e.g. vs e.g. (same for i.e.) and Oxford (or not) comma. I also noticed the use of acronyms with no introduction. I am going through the main document and checking all this.

jcohen02 commented 10 months ago

Thanks @ljgarcia. We discussed this in the meeting. I'm also going to go through and check these things. I actually had an issue with updating the PDF and it seems the version I was using was a bit out of date - many of the American English spellings have now been switched to British English by the spell check action that has been added. We decided that since everything has already been switched, we would stick with British English for the spellings. If you spot anything that has not been picked up by the spell check that's great - I think several people will plan to do a full read through over the next week to check things through too.

CaptainSifff commented 9 months ago

We currently have 3 links. that link to the example personas of BioExcel. I guess this is fine since it seems to rather hard to cite.

MakisH commented 9 months ago

We currently have 3 links. that link to the example personas of BioExcel. I guess this is fine since it seems to rather hard to cite.

These links are, however, not printable. I guess this is why URLs such as CodeRefinery ([7]) are currently in the references. I can fix those.

Footnotes are also an option to distinguish between URLs and proper academic citations.

Language: I'm noticing some minor inconsistencies in the use of Britsh and International/US English. Some of this may be my fault but I also noticed that when I then tried to ensure that I'm using US English spellings, e.g. professionalize as opposed to professionalise, the spell check run tells me that spelling is wrong. Although I see uses of other words such as organization, instead of organisation which the spell check process isn't picking up. I'm happy with whatever approach we choose to take but we should probably aim to ensure we are consistent.

Learned something today: Besides the US and British spellings, there is also the Oxford spelling, which is British but with -ize. It is apparently common in publications. And, reading that the -ize is closer to the Greek root -ίζω, suddenly it all makes sense why it feels more natural to me. :sweat_smile:

I am now trying to parse the text through LanguageTool, and I got this suggestion when setting to British English:

Starting check in English (British)...

  1. Line 14, column 83 Message: Would you like to use the Oxford spelling organizations? The spelling 'organisations' > is also correct. (deactivate) Correction: organizations Context: ...SE roles, proposing recommendations for organisations, and giving examples of > future speciali... More info: https://languagetool.org/insights/post/ise-ize/

Searching for ize and ization, I only find digitalization. Both seem to be used in British English literature (Google Ngram).

I think that the -ize/-ise is fine as it is. @jcohen02 what do you think?

CaptainSifff commented 9 months ago

For the links, then let's move to foornotes. With regard to the english dialect, I'd suggest not to open another box, since we are now consistent for this publication.

jcohen02 commented 9 months ago

We currently have 3 links. that link to the example personas of BioExcel. I guess this is fine since it seems to rather hard to cite.

These links are, however, not printable. I guess this is why URLs such as CodeRefinery ([7]) are currently in the references. I can fix those.

Footnotes are also an option to distinguish between URLs and proper academic citations.

I think footnotes are OK at this stage if there are web references that are otherwise hard to cite. However, if we're aiming to submit this to a journal, I suspect we'll probably need to add proper reference entries for these?

Searching for ize and ization, I only find digitalization. Both seem to be used in British English literature (Google Ngram).

I think that the -ize/-ise is fine as it is. @jcohen02 what do you think?

Thanks for the detailed message about this in your earlier comment @MakisH. Happy to go with whatever you decide here but in the context of the single use of "digitalization", my personal preference would be for "digitalisation" - this is partly just personal preference but also I think it's more consistent with the approach used in the rest of the paper.

CaptainSifff commented 9 months ago

I converted the reamining links into URL footnotes. Together wth all the work by @MakisH I think we can close this here.

MakisH commented 9 months ago

I converted the reamining links into URL footnotes. Together wth all the work by @MakisH I think we can close this here.

Oh, I was about to start working on that. Perfect timing, thanks!

MakisH commented 9 months ago

@CaptainSifff moving the rest of the URLs to footnotes (everything that does not have an author, i.e., [7], [8], [11], [12], [13], [14] and more) would drop the length by another half page at least (and get rid of the last single-line page). Shall I try that?

CaptainSifff commented 9 months ago

At one point we had decided, to include proper citations to Projects and their homepages and treat them as proper citable entities. So assuming this holds for all of the references you mentioned, I would like to keep it like that.