From 61e12bc1c51de453ead235629844dab597a646d4 Mon Sep 17 00:00:00 2001 From: Carlos Martinez Date: Mon, 14 Dec 2020 09:53:12 +0100 Subject: [PATCH 1/2] Update text based on suggestions from Jurriaan and Mateusz --- static/json/recommendations.json | 42 ++++++++++++++++---------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/static/json/recommendations.json b/static/json/recommendations.json index c72dd79..924d488 100644 --- a/static/json/recommendations.json +++ b/static/json/recommendations.json @@ -15,12 +15,12 @@ { "type" : "WYSIWYG", "title": "Why public", - "text" : "

Developing scientific software in publicly accessible repositories enables early involvement of users, helps build collaborations, contributes to the reproducibility of results generated by the software, facilitates software reusability, and contributes to improving software quality. Taken together, this ensures that your software has the best chance of being used by as many people as possible while promoting transparency.

" + "text" : "

Developing scientific software in publicly accessible repositories enables early involvement of users, helps build collaborations, contributes to the reproducibility of results generated by the software, facilitates software reusability, and contributes to improving software quality. Taken together, this ensures that your software has the best chance of being used by as many people as possible while promoting transparency.

" }, { "type" : "WYSIWYG", "title": "Why version control", - "text" : "

Using a version control system allows you to easily track changes in your software, both your own changes as well as those made by collaborators. There are many flavors of version control systems, ranging from older systems such as CVS and Subversion to more modern ones such as Git, Mercurial, and Bazaar. By configuring your version control system to use GitHub, GitLab or Bitbucket, you’ll even have backups of every version of the software you ever made. Additionally, those platforms offer collaboration tools such as an issue tracker and project management tools, and you’ll be able to use third-party services such as code quality checkers, correctness checkers, and a lot more.

" + "text" : "

Using a version control system allows you to easily track changes in your software, both your own changes as well as those made by collaborators. There are many flavors of version control systems, ranging from older systems such as CVS and Subversion to more modern ones such as Git, Mercurial, and Bazaar. By configuring your version control system to use GitHub, GitLab or Bitbucket, you’ll even have backups of every version of the software you ever made. Additionally, those platforms offer collaboration tools such as an issue tracker and project management tools, and you’ll be able to use third-party services such as code quality checkers, correctness checkers, and a lot more.

" } ] }, @@ -34,11 +34,11 @@ "paragraphs" : [ { "type" : "WYSIWYG", - "text" : "

Git is the most feature-rich, most modern and most popular by a good margin, and we heartily recommend you use it for all you version control needs. To get the best out of Git, use it in combination with GitHub.com, Bitbucket.org, or GitLab.com.

" + "text" : "

Git is the most feature-rich, most modern and most popular version control system by a good margin, and we heartily recommend you use it for all you version control needs. To get the best out of Git, use it in combination with GitHub.com, Bitbucket.org, or GitLab.com.

" }, { "type" : "WYSIWYG", - "text" : "" + "text" : "" } ] } @@ -64,7 +64,7 @@ "paragraphs" : [ { "type" : "WYSIWYG", - "text" : "

Any creative work (including software) is automatically protected by copyright. Even when the software is available via code sharing platforms such as GitHub, no one can use it unless they are explicitly granted permission. This is done by adding a software license, which defines the set of rules and conditions for people who want to use the software. Finally, be aware that you, as the developer of a given piece of software, may not be a copyright owner of the code you write. Usually the copyright holder of a work is the employer (or hiring party) and not the author of the work.

" + "text" : "

Any creative work (including software) is automatically protected by copyright. Even when the software is available via code sharing platforms such as GitHub, no one can legally use it unless they are explicitly granted permission. This is done by adding a software license, which defines the set of rules and conditions for people who want to use the software. Finally, be aware that you, as the developer of a given piece of software, may not be a copyright owner of the code you write. Usually the copyright holder of a work is the employer (or hiring party) and not the author of the work.

" } ] }, @@ -78,7 +78,7 @@ "paragraphs" : [ { "type" : "WYSIWYG", - "text" : "

We recommend you stick to one of the more popular licenses. Because these are typically written by lawyers, the license text is precise in expressing its terms. While that carries the unfortunate side effect of being difficult to understand, the widespread use of the more popular licenses means that there is a larger number of people who understand how the letter of the law should be interpreted.

" + "text" : "

We recommend you stick to one of the more popular licenses. Because these are typically written by lawyers, the license text is precise in expressing its terms. While that carries the unfortunate side effect of being difficult to understand, the widespread use of the more popular licenses means that there is a larger number of people who understand how the letter of the law should be interpreted.

" }, { "type" : "WYSIWYG", @@ -94,7 +94,7 @@ "meta" : { "ogImage" : "/img/og.png", "ogTitle" : "Add a Licence", - "ogDescription" : "Any creative work (including software) is automatically protected by copyright. Even when the software is available via code sharing platforms such as GitHub, no one can use it unless they are explicitly granted permission. This is done by adding a software license, which defines the set of rules and conditions for people who want to use the software. Finally, be aware that you, as the developer of a given piece of software, may not be a copyright owner of the code you write. Usually the copyright holder of a work is the employer (or hiring party) and not the author of the work." + "ogDescription" : "Any creative work (including software) is automatically protected by copyright. Even when the software is available via code sharing platforms such as GitHub, no one can legally use it unless they are explicitly granted permission. This is done by adding a software license, which defines the set of rules and conditions for people who want to use the software. Finally, be aware that you, as the developer of a given piece of software, may not be a copyright owner of the code you write. Usually the copyright holder of a work is the employer (or hiring party) and not the author of the work." } }, { @@ -112,7 +112,7 @@ "paragraphs" : [ { "type" : "WYSIWYG", - "text" : "

For others to make use of your work, they need to be able to find it first. Community registries are like the yellow pages for software -- registering your software makes it easier for others to find it, particularly through the use of search engines such as Google. Community registries typically employ metadata to describe each software package. With metadata, search engines are able to get some idea of what the software is about, what problem it addresses, and what domain it is suited for. In turn, this helps improve the ranking of the software in the search results -- better metadata means better ranking.

" + "text" : "

For others to make use of your work, they need to be able to find it first. Community registries are like the yellow pages for software -- registering your software makes it easier for others to find it, particularly through the use of search engines such as Google. Community registries typically employ metadata to describe each software package. With metadata, search engines are able to get some idea of what the software is about, what problem it addresses, and what domain it is suited for. In turn, this helps improve the ranking of the software in the search results -- better metadata means better ranking.

" } ] }, @@ -126,7 +126,7 @@ "paragraphs" : [ { "type" : "WYSIWYG", - "text" : "

Community registries come in many flavors. Choosing the one that is best suited for your needs can be tricky. Here are some things to think about:

" + "text" : "

Community registries come in many flavors. Choosing the one that is best suited for your needs can be tricky. Here are some things to think about:

" }, { "type" : "WYSIWYG", @@ -134,17 +134,17 @@ }, { "type" : "WYSIWYG", - "text" : "

Finally, ask a couple of colleagues which registries they would use if they were looking for software like yours.

" + "text" : "

Finally, ask a couple of colleagues which registries they would use if they were looking for software like yours.

" }, { "type" : "button", - "text" : "View all research software registries", + "text" : "View a list of software registries", "link" : "https://github.com/NLeSC/awesome-research-software-registries", "icon" : "https://camo.githubusercontent.com/1997c7e760b163a61aba3a2c98f21be8c524be29/68747470733a2f2f617765736f6d652e72652f62616467652e737667" } ] } - + ], "meta" : { "ogImage" : "/img/og.png", @@ -167,7 +167,7 @@ "paragraphs" : [ { "type" : "WYSIWYG", - "text" : "

Citation helps software developers be recognized for their work. Additionally, citation is an integral part of scientific accountability and reproducibility, but accurately citing software is inherently more difficult than citing a paper. To an outsider especially, even seemingly trivial things such as identifying who should be recognized as an author can be difficult. It is therefore convenient when software developers themselves provide the information necessary to enable citation.

" + "text" : "

Citation helps software developers be recognized for their work. Additionally, citation is an integral part of scientific accountability and reproducibility, but accurately citing software is inherently more difficult than citing a paper. To an outsider especially, even seemingly trivial things such as identifying who should be recognized as an author can be difficult. It is therefore convenient when software developers themselves provide the information necessary to enable citation.

" } ] }, @@ -181,7 +181,7 @@ "paragraphs" : [ { "type" : "WYSIWYG", - "text" : "

CodeMeta and the Citation File Format were specifically designed to enable citation of software and will likely meet your needs. For either one, you write a plain text file with citation metadata, which you then distribute with your software.

" + "text" : "

CodeMeta and the Citation File Format were specifically designed to enable citation of software and will likely meet your needs. For either one, you write a plain text file with citation metadata, which you then distribute with your software.

" }, { "type" : "WYSIWYG", @@ -197,7 +197,7 @@ }, { "type" : "WYSIWYG", - "text" : "" + "text" : "" } ] } @@ -223,7 +223,7 @@ "paragraphs" : [ { "type" : "WYSIWYG", - "text" : "

Checklists help you write good quality software. What exactly constitutes 'good quality' depends on the specific application of the software, but typically covers things like documenting the source code, using continuous testing, and following standardized code patterns.

" + "text" : "

Checklists help you write good quality software. What exactly constitutes 'good quality' depends on the specific application of the software, but typically covers things like documenting the source code, using continuous testing, and following standardized code patterns.

" } ] }, @@ -237,23 +237,23 @@ "paragraphs" : [ { "type" : "WYSIWYG", - "text" : "

There are many checklists available. We find that the most useful checklist are those that

" + "text" : "

There are many checklists available. We find that the most useful checklist are those that

" }, { "type" : "WYSIWYG", - "text" : "
  1. Allow for a granular evaluation of a software package, as opposed to just pass or fail
  2. Explain the rationale behind each item in the checklist
  3. Explain how to get started with implementing each item in the checklist
" + "text" : "
  1. Allow for a granular evaluation of a software package, as opposed to just pass or fail
  2. Explain the rationale behind each item in the checklist
  3. Explain how to get started with implementing each item in the checklist
" }, { "type" : "WYSIWYG", - "text" : "

We recommend that you include the checklist as part of the README, for example as a badge or by including the checklist as a MarkDown table. The point is decidedly not to show perfect compliance, but rather to be transparent about the state of the code while providing the necessary guidance on which aspects could be improved.

" + "text" : "

We recommend that you include the checklist as part of the README, for example as a badge or by including the checklist as a MarkDown table. The point is decidedly not to show perfect compliance, but rather to be transparent about the state of the code while providing the necessary guidance on which aspects could be improved.

" }, { "type" : "WYSIWYG", - "text" : "

One of our favorite checklists that meets these criteria is the Badge Program developed by the Core Infrastructures Initiative, but there are many other checklists to choose from. Here is a list of some candidates:

" + "text" : "

One of our favorite checklists that meets these criteria is the Badge Program developed by the Core Infrastructures Initiative, but there are many other checklists to choose from. Here is a list of some candidates:

" }, { "type" : "WYSIWYG", - "text" : "" + "text" : "" } ] } From 80cb5aafa69051f421bf6bc5e941b93a86694e25 Mon Sep 17 00:00:00 2001 From: Carlos Martinez Date: Mon, 14 Dec 2020 16:46:05 +0100 Subject: [PATCH 2/2] Update static/json/recommendations.json --- static/json/recommendations.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/static/json/recommendations.json b/static/json/recommendations.json index 924d488..80303e0 100644 --- a/static/json/recommendations.json +++ b/static/json/recommendations.json @@ -34,7 +34,7 @@ "paragraphs" : [ { "type" : "WYSIWYG", - "text" : "

Git is the most feature-rich, most modern and most popular version control system by a good margin, and we heartily recommend you use it for all you version control needs. To get the best out of Git, use it in combination with GitHub.com, Bitbucket.org, or GitLab.com.

" + "text" : "

Git is the version control system which is most feature-rich, most modern and most popular by a good margin, and we heartily recommend you use it for all you version control needs. To get the best out of Git, use it in combination with GitHub.com, Bitbucket.org, or GitLab.com.

" }, { "type" : "WYSIWYG",