Documentation Refactoring

README.md

@@ -1,75 +1,81 @@
-![banner.jpg](images/banner.jpg)
 
-# Best practices
+<div align = center>
 
-Welcome at the best practices for git, research software development, and research data management. This repository was created for and by researchers and support staff of Utrecht University. The community is strongly encouraged to share best practices in this repository. 
+![Banner]
 
-## Topics
+<br>
 
-### Using Git and Github
+[![Badge License]][License]   
+[![Badge Contribute]][Contribute]
 
-Git is free and open-source software for version management. It was created in the 2005 and is nowadays the facto-standard version control software for software development. GitHub is an online service based on Git that makes it easy to work together and share your work openly. It can also be used as a backup of your local work. Learning Git and GitHub can be steep in the beginning, but will be worth all the effort. 
+<br>
 
-**Quick start**
+Welcome to the best practices for git, research software <br>
+development and research data management.
 
-1. [Create GitHub Account](https://github.com/join)
-2. [Download and install GitHub Desktop](https://desktop.github.com/)
-3. [Authenticate GitHub for Utrecht University](https://github.com/UtrechtUniversity/getting-started) [OPTIONAL]
-4. [Create your first repository with Github Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/overview)
+This repository was created for and by researchers <br>
+as well as support staff of the **University of Utrecht**.
 
-**Read more**
+The community is strongly encouraged <br>
+to share best practices in this repository. 
 
-- [Git vs Github – Demystifying The Differences](https://www.edureka.co/blog/git-vs-github/)
+<br>
+<br>
 
-### FAIR Software
+## Topics
 
-The [FAIR principles](https://www.nature.com/articles/sdata201618) are a framework that is widely used in research data management. The acronym stands for Findable, Accessible, Interoperable and Reusable. Recently, the FAIR principles are applied to [research software](https://content.iospress.com/articles/data-science/ds190026) by Anna-Lena Lamprecht et al (2020). 
+<br>
 
-**Quick start**
+<div align = center>
 
-- [Five Recommendations for FAIR Software](https://fair-software.eu/)
+[![Button Usage]][Usage]   
+[![Button FAIR]][FAIR]
 
-**Tools**
+[![Button Visible]][Visible]   
+[![Button Contribute]][Contribute]
 
-- [Python package to analyze a GitHub or GitLab repository's compliance with the fair-software.eu recommendations](https://github.com/fair-software/howfairis)
+</div>
 
-**Read more**
+<br>
+<br>
 
-- Paper on FAIR software principles: [Towards FAIR principles for research software (Lamprecht et al, 2020)](https://content.iospress.com/articles/data-science/ds190026)
-- Paper on FAIR data principles: [The FAIR Guiding Principles for scientific data management and stewardship](https://www.nature.com/articles/sdata201618)
-- Working group *FAIR for Research Software (FAIR4RS)* https://www.rd-alliance.org/groups/fair-research-software-fair4rs-wg
 
-### Visibility
 
-To facilitate reuse of your wonderful work, people should be able to find you and your work. GitHub offers a lot of options to make your research software more visible. 
+## Contact
 
-**Quick start**
+This repository is currently maintained by the <br>
+**[Utrecht University Open Science Programme][Open Science]** <br>
+as well as the **ITS Department**.
 
-- Add a [bio and profile README to your GitHub account](https://docs.github.com/en/github/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-profile) 
-- Add GitHub profile to [your staff page](https://www.uu.nl/staff/)
-- Add [topics](https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/classifying-your-repository-with-topics) to your repository to increase findability https://github.com/topics. There is also topic for [`#utrecht-university`](https://github.com/topics/utrecht-university).
+*Are you an Utrecht University researcher or support* <br>
+*staff and willing to help maintaining this repository?*
 
-**Read more**
+***Reach out to [email protected]***
 
-- [Utrecht University Visibility To-Do List](https://www.uu.nl/en/university-library/advice-support-to/researchers/visibility/research-visibility-check/visibility-to-do-list)
-- Use [Github Pages](https://pages.github.com/) to publish a project overview and link to all relevant repositories and collaborators
+<br>
 
 
-## Contributing
+<!----------------------------------------------------------------------------->
 
-Contributions to this repository are very welcome. The main idea of this repository is to have a collection of good practices tailored to researchers at Utrecht University. 
+[Open Science]: https://www.uu.nl/en/research/open-science
+[Contribute]: Topics/Contributing.md
+[Visible]: Topics/Visibility.md
+[Usage]: Topics/Git%20&%20GitHub.md
+[FAIR]: Topics/FAIR%20Software.md
 
-The following contribution guidelines apply to this repository: 
+[License]: LICENSE
+[Banner]: images/banner.jpg
 
-- Open a Pull Request or file an Issue if you have anything to add, change, or delete. 
-- Browse the [issue with label Help Wanted](https://github.com/UtrechtUniversity/best-practices/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) to see what you can contribute 
-- Create a new topic if necessary. 
-- Use an editorial style guide for writing, preferably the [Google developer documentation style guide](https://developers.google.com/style). 
 
-## License
+<!---------------------------------[ Badges ]---------------------------------->
 
-The content in this repository is licensed [CC0-1.0](/LICENSE) (release to the public domain).
+[Badge Contribute]: https://img.shields.io/badge/Contributions-Welcome-3a6620.svg?style=for-the-badge&labelColor=569A31&logoColor=white&logo=GitHub
+[Badge License]: https://img.shields.io/badge/-Zero-ae6c18.svg?style=for-the-badge&labelColor=EF9421&logoColor=white&logo=CreativeCommons
 
-## Contact
 
-This repository is currently maintained by the [Utrecht University Open Science Programme](https://www.uu.nl/en/research/open-science), and the ITS department. Are you an Utrecht University researcher or support staff and willing to help maintaining this repository? Reach out to [email protected]. 
+<!---------------------------------[ Buttons ]--------------------------------->
+
+[Button Contribute]: https://img.shields.io/badge/How_To_Contribute-569a31.svg?style=for-the-badge&logoColor=white&logo=GitExtensions
+[Button Visible]: https://img.shields.io/badge/Visibility-AA344D.svg?style=for-the-badge&logoColor=white&logo=Facepunch
+[Button Usage]: https://img.shields.io/badge/Git_&_GitHub-00A8E1.svg?style=for-the-badge&logoColor=white&logo=GitHub
+[Button FAIR]: https://img.shields.io/badge/FAIR_Software-009688.svg?style=for-the-badge&logoColor=white&logo=Asana

Topics/Contributing.md

@@ -0,0 +1,47 @@
+
+# Contributing
+
+The idea of this repository is to have a<br>
+collection of good practices tailored to <br>
+researchers of the **Utrecht University**.
+
+<br>
+<br>
+
+## Guidelines
+
+-   Open a **[Pull Request]** or file an Issue if you <br>
+    have anything to ***add*** , ***change*** or ***delete***.
+
+    <br>
+
+-   Browse the **[Issues]** that are labeled <br>
+
+    ![Badge Help]
+
+    to see what you can contribute to.
+
+    <br>
+
+-   *Create a new topic if necessary.*
+
+    <br>
+
+-   Use an editorial style guide for writing, preferably <br>
+    the ***[Google developer documentation style guide][Style Guide]*** . 
+
+<br>
+
+
+
+<!----------------------------------------------------------------------------->
+
+[Pull Request]: https://github.com/UtrechtUniversity/best-practices/pulls
+[Style Guide]: https://developers.google.com/style
+[Issues]: https://github.com/UtrechtUniversity/best-practices/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22
+
+
+<!---------------------------------[ Badges ]---------------------------------->
+
+[Badge Help]: https://img.shields.io/badge/-_Ｈｅｌｐ_Ｗａｎｔｅｄ_-014138
+

Topics/FAIR Software.md

@@ -0,0 +1,75 @@
+# FAIR Software
+
+The **[FAIR principles][FAIR]** are a framework that is <br>
+widely used in research data management.
+
+<br>
+
+The acronym stands for:
+
+ **Ｆ indable** <br>
+ **Ａ ccessible** <br>
+ **Ｉ nteroperable** <br>
+ **Ｒ eusable**
+
+<br>
+
+Recently, the **FAIR Principles** have been applied in the <br>
+**[Research Software]** by  `Anna-Lena Lamprecht et al` .
+
+*( 2020 )* 
+
+<br>
+<br>
+
+### Quick Start
+
+-   **[Five Recommendations][FAIR Recommendations]** for **FAIR** Software.
+
+<br>
+<br>
+
+### Tools
+
+-   **[Python Package][FAIR Software]** to analyze a **GitHub** / **GitLab** repository's <br>
+    compliance with the  `fair-software.eu`  recommendations.
+
+<br>
+<br>
+
+### More
+
+<br>
+
+-   **FAIR Software Principles [ Paper ]**
+
+    [`Towards FAIR principles for research software (Lamprecht et al, 2020)`][FAIR Software Principles]
+
+<br>
+
+-   **FAIR Data Principles [ Paper ]**
+
+    [`The FAIR Guiding Principles for scientific data management and stewardship`][FAIR Data Principles]
+
+<br>
+
+-   **Working Group** 
+
+    [`FAIR for Research Software ( FAIR4RS )`][FAIR Group]
+
+<br>
+
+
+<!----------------------------------------------------------------------------->
+
+[Research Software]: https://content.iospress.com/articles/data-science/ds190026
+
+
+<!-----------------------------------{ FAIR }---------------------------------->
+
+[FAIR Software Principles]: https://content.iospress.com/articles/data-science/ds190026
+[FAIR Data Principles]: https://www.nature.com/articles/Headersdata201618
+[FAIR Recommendations]: https://fair-software.eu/
+[FAIR Software]: https://github.com/fair-software/howfairis
+[FAIR Group]: https://www.rd-alliance.org/groups/fair-research-software-fair4rs-wg
+[FAIR]: https://www.nature.com/articles/sdata201618

Topics/Git & GitHub.md

@@ -0,0 +1,56 @@
+
+# Using Git & GitHub
+
+**Git** is  `free`  and  `open-source`  version management system.
+
+<br>
+
+*It was created in `2005` and is nowadays the* <br>
+*de facto standard version control software* <br>
+*for software development.*
+
+<br>
+
+**GitHub** is an online service based on **Git** <br>
+that makes it easy to work together and <br>
+share your work openly.
+
+<br>
+
+***It can also be used as a backup of your local work.***
+
+<br>
+
+Learning **Git** and **GitHub** can be steep in the <br>
+beginning, but ***will be worth all the effort***. 
+
+<br>
+<br>
+
+### Quick start
+
+1.        [Make a GitHub account][Create Account]
+
+2.        [Download / Install `GitHub Desktop`][Install GitHub]
+
+3.  〈  [Connect your account to the university][Getting Started]  〉  *Optional*
+
+4.        [Create your first repository][Create Repository]
+
+<br>
+<br>
+
+### More
+
+-   [`Git vs Github – Demystifying The Differences`][Git Vs GitHub]
+
+<br>
+
+
+<!----------------------------------------------------------------------------->
+
+[Create Repository]: https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/overview
+[Getting Started]: https://github.com/UtrechtUniversity/getting-started
+[Install GitHub]: https://desktop.github.com/
+[Create Account]: https://github.com/join
+[Git Vs Github]: https://www.edureka.co/blog/git-vs-github/

Topics/Visibility.md

@@ -0,0 +1,58 @@
+
+# Visibility
+
+To facilitate the reuse of your wonderful work, <br>
+people should be able to find you & your work.
+
+**GitHub** offers a lot of options to make <br>
+your research software more visible. 
+
+<br>
+<br>
+
+## Quick Start
+
+<br>
+
+-   **[Customize Your Profile][Profile Customization]** by adding a **Bio** and a **README** .
+
+<br>
+
+-   Link your **Github Profile** to your **[Staff Page]** .
+
+<br>
+
+-   Add **[Topics]** to your repository to increase **[Findability]** .
+
+    *There is also topic for [`#utrecht-university`][Topic University].*
+
+<br>
+<br>
+
+## More
+
+<br>
+
+-   **Utrecht University** visibility **[Todo List]** .
+
+<br>
+
+-   Use **[Github Pages]** to publish a project overview and <br>
+    link to all the relevant repositories and collaborators.
+
+<br>
+
+
+<!----------------------------------{ GitHub }--------------------------------->
+
+[Profile Customization]: https://docs.github.com/en/github/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-profile
+[Topic University]: https://github.com/topics/utrecht-university
+[GitHub Pages]: https://pages.github.com/
+[Findability]: https://github.com/topics
+[Topics]: https://docs.github.com/en/github/administering-a-repository/managing-repository-settings/classifying-your-repository-with-topics
+
+
+<!--------------------------------{ University }------------------------------->
+
+[Todo List]: https://www.uu.nl/en/university-library/advice-support-to/researchers/visibility/research-visibility-check/visibility-to-do-list
+[Staff Page]: https://www.uu.nl/staff/