Merge pull request #2 from manuGil/review

Edit content of first part

gitcodev/curriculum.md

@@ -1,40 +1,40 @@
 # Curriculum
 
-Version control is an esential tool in software development. It enables the tracking of changes in the code source, and the management of multiple versions. Git is version control system that allows asyncronous development, and currently, the most popular version control system. 
+Version control is an essential tool in software development. It enables the tracking of changes in the code source and the management of multiple versions. Git is a version control system that allows asynchronous development and is currently the most popular version control system. 
 
-Collaborative development is a software development approach that can help researchers to organize their software project, foster collaboration among their peers and create a community around open source research software.
-Researchers involved or experting to get invovled in the developing of research software can benefit greatly of mastering the basics of collaborative development.
+Collaborative development is a software development approach that can help researchers organise their software projects, foster collaboration among their peers and create a community around open-source research software.
+Researchers involved or expecting to be involved in developing research software can benefit greatly from mastering the basics of collaborative development.
 
 
 ## Prerequisites
 
 Knowledge and experience in using the command-line interface (CLI) with Unix Shell to perform the following tasks:
 
-* to navigate and visualise content of directories (folders);
+* to navigate and visualise the content of directories (folders);
 * to create, copy, move and delete files and directories;
-* to edit files with terminal-based text editors (such as nano, vim, emacs, etc);
+* to edit files with terminal-based text editors (such as Nano, vim, emacs, etc);
 * to visualise hidden files and directories;
 * to redirect and append a command output to a file.
 
 ## Tools and Materials
 
 * Unix Shell.
 * Git.
-* GitHub account, or account on similar platform.
-* A laptop with administrative privileges  running Mac, Linux or Windows operating system.
-
+* GitHub account or account on a similar platform.
+* A laptop with administrative privileges running MacOS, Linux or Windows.
 
+(course-units)=
 ## Course Units
 
-This course is organized into lessons, episodos and topic. The course consist of **Lessons**. Each Lesson is further divided into **Episodes**, and then into **Topics**. The order in which lessons, episodes and topic is organized is the result of extensive descussions on the best way to develiver the course to an audience with little to intermediate previous experience and knowldege, and the experience gather from delivering the course to two groups of mostly PhD cantidates. 
+This course is organised into lessons, episodes and topics. The course consists of **Lessons**. Each Lesson is divided into **Episodes** and then into **Topics**. The order in which lessons, episodes and topic is organised is the result of extensive discussions on the best way to deliver the course to an audience with little to intermediate previous experience and knowledge and the experience gathered from providing the course to two groups of mostly PhD candidates. 
 
 ### Lesson 1: Fundamental Operations with Git 
 
 **Learning Objectives:**
 - Understand the basics of version control.
-- Use Git for creatig repositories and commit changes.
+- Use Git to create repositories and commit changes.
 - Apply Git operations to track, reverse and delete changes in working documents.
-- Organize tracked changes in the Git history.
+- Organise tracked changes in the Git history.
 
 <details>
 <summary>
@@ -64,10 +64,10 @@ This course is organized into lessons, episodos and topic. The course consist of
 
 **Learning Objectives:**
 - Understand the concept of branches in Git repositories.
-- Apply Git operations for creating and merging branches in a local Git repository.
+- Apply Git operations to create and merge branches in a local Git repository.
 - Understand the concepts of bare and remote Git repositories. 
 - Clone and push changes to remote Gir repositories.
-- Syncronize changes between local and remote Git repositories.
+- Synchronise changes between local and remote Git repositories.
 
 
 <details>
@@ -80,7 +80,7 @@ This course is organized into lessons, episodos and topic. The course consist of
 | **2.1** | **Branching** | 
 | --- | Create, rename, change, and delete branches | 
 | --- | Develop and compare branches | 
-| --- | Visualise and merge branches, and resolve conflicts | 
+| --- | Visualise and merge branches and resolve conflicts | 
 | **2.2** | **Operations with remotes** | 
 | --- | Create a bare repositories |
 | --- | Cloning and pushing to upstreams |
@@ -92,11 +92,11 @@ This course is organized into lessons, episodos and topic. The course consist of
 ### Lesson 3: Collaborative Software Development
 
 **Learning Objectives:**
-- Collaborate in software project using one of the Git repository platforms such as GitHub.
-- Undestand the principles of managing research software projects.
-- Orgaize a sofware development team by defining roles and resposibilties.
+- Collaborate on software projects using one of the Git repository platforms such as GitHub.
+- Understand the principles of managing research software projects.
+- Organise a software development team by assigning roles and responsibilities.
 - Contribute to the development of research software using a collaborative approach.
-- Undestand the difference between centrilized and shared collaborative workflow and when to use them.
+- Understand the difference between centralised and shared collaborative workflow and when to use them.
 - Contribute to open or close software projects using features such as issues, code changes, and pull/merge requests.
 
 <details>
@@ -111,11 +111,11 @@ This course is organized into lessons, episodos and topic. The course consist of
 | --- | Exploring the GitHub GUI |
 | --- | Collaborating |
 | **3.2** | **Collaborative Development for Research Software** |
-| --- | When to aim for a collaborative approach? |
+| --- | When should we aim for a collaborative approach? |
 | --- | Management strategies |
 | --- | Roles and responsibilities |
 | --- | Documenting issues |
-| --- | Centralize workflow: branching
+| --- | Centralise workflow: branching
 | --- | Pull requests
 | --- | Shared workflow: forking
 
@@ -125,12 +125,12 @@ This course is organized into lessons, episodos and topic. The course consist of
 
 **Learning Objectives:**
 
-- Understand the important of contribution guidelines and best practices to manage collaboration in a research software projects.
-- Organize a sofware team independently around activities related to collaborative software development.
-- Understand the impact coder reviews and best practices on the quality of software.
-- Conduct code reviews as part of a research software team.
+- Understand the importance of contribution guidelines and best practices to manage collaboration in research software projects.
+- Organise a software team independently to work on activities related to collaborative software development.
+- Understand the impact of code reviews and best practices on software quality.
+- Perform code reviews as part of a research software team.
 - Apply best practices when conducting code reviews. 
-- Describe what are best practices related to sofware licensing, citation, semantic versioning, and software releases.
+- Describe best practices related to licensing, citation, semantic versioning, and releases or software.
 
 <details>
 <summary>

gitcodev/intro.md

@@ -10,45 +10,48 @@ h3.dancing {
 }
 </style>
 
+
 # Introduction
 
 This website describes a curriculum for a short course on *Version Control and collaboratie Development for Research Software*. 
 The content has been designed specifically for the instructors ('train the trainers') and not for the learners. A derivative document suited to learners would require adapted design, format and distribution.
 
+`````{admonition} Work in progress
+:class: important
+Parts of this curriculum are work in progress. A revised version will be available by September 2024.
+`````
 
 ## Why do we need a new course on version control?
-
 To any educator reading this, it will be evident that having new topics to teach is not the only reason for designing new teaching materials. 
 Changes in learning objectives, the target audience, or the teaching approaches are also valid reasons to 
 design and develop new teaching materials.  
-Therefore, we could answer the question: *why do we need a new course  about version control with Git?* by simple stating: 
-*this course has different learning objective and teaching approaches*. 
+Therefore, we could answer the question: *why do we need a new course  about version control with Git?* by simply stating: 
+*This course has different learning objectives and teaching approaches*. 
 
-However, more curious readers would like to know in which ways it is different. Which objectives  and teaching approaches are different? 
-How does these materials compared to the ones by author 'A' or organisation 'O'? 
-Which topics are different? and How different are they? 
-Are these materials better those in course 'C'?
-Proving scientific evidence of the differences in this course will require to spend a considerable amount of time in disecting, analysing and comparing with courses covering simialr topics.
-We have deliverly chosen to not engage in that endevour; instead, we have chosen to put our efforts to better use and focus on improving the way version control and collaborative development is thaught to researchers in technical univesities.
+However, more curious readers would like to know in which ways it is different. Which objectives and teaching approaches are different? 
+How do these materials compare to the ones by author 'A' or organisation 'O'? 
+Which topics are different? And how different are they? 
+Are these materials better than those in course 'C'?
+Proving scientific evidence of the differences in this course will require spending considerable time dissecting, analysing and comparing with courses covering similar topics.
+We have chosen not to engage in that endeavour; instead, we have decided to put our efforts to better use and focus on improving how version control and collaborative development are taught to researchers in technical universities.
 
-Therefore, we do not provide anwers to the questions listed above. Though, we do not mean to discourage anyone, 
-who wishes to put the effort on finding answers, from pursuing so. 
-Instead, we explain what our motivation for developing this course is, and hope that will sufy readers who share our motivation. We encourge them to adopt, adapt and reuse the contents of this course.
+Therefore, we do not provide answers to the questions listed above. Though we do not mean to discourage anyone, 
+who wishes to put the effort into finding answers from pursuing so. 
+Instead, we explain our motivation for developing this course and hope it will satisfy readers who share our motivation. We encourage them to adopt, adapt and reuse the contents of this course.
 
 ## Motivation
-
 After teaching introductory courses on version control using Git at the [Delft University of Technology](https://www.tudelft.nl/), 
-recurring feedback provided by participants, mainly early-carreer reseachers such as PhD candiates and post-docs, made evident that such courses were highly appreciated and interesting. However, participants also often mentioned that after the courses, they did not feel confident in applying what was learned to their own research.
-And they did not know how they could apply the recently adquired skills to their research projects, 
-even when such projects involve writing code for themselves or for their research groups.
+recurring feedback provided by participants, mainly early-career researchers such as PhD candidates and post-docs, made evident that such courses were highly appreciated and interesting. However, participants also often mentioned that after the courses, they did not feel confident applying what was learned to their research.
+They did not know how they could apply the recently acquired skills to their research projects, 
+even when such projects involve writing code for themselves or their research groups.
 
-On the other had, during my role as a research software engineer, I often find myself explaining early-carreer and well-stablished researchers how to adopt and adapt practices that are common in collaborative software development into their work and the work of their research groups. That meant that I could spend less time contributing directly to the development of their research sofware. In more than one case, the benefits of changing the way researchers approach development of research software werer evident. 
-However, in those cases there was also an innitial reluctance in changing they way developing research software was made. 
+On the other hand, during my role as a research software engineer, I often find myself explaining to early-career and well-established researchers how to adopt and adapt practices prevalent in collaborative software development into their work and the work of their research groups. That meant I could spend less time contributing directly to developing their research software. In more than one case, the benefits of changing how researchers approach research software development were evident. 
+However, in those cases, there was also an initial reluctance to change the way developing research software was made. 
 
-These experiences convinced me that researchers will benefit from understading what software development entitles and adopt some of the best practices without they needing to become sofware engineers themselves. 
-If  that could be achived, research software will be of better quality, software as a research output would be easier to maintain which will increase the likelihood of research results to be reproducible for a longer time, the productity among researchers that continously engage in the development of research software can be increase; and the time spent on direclty working on research software, as a software engineer, could be increased to the benefit of the researchers themselves. 
+These experiences convinced me that researchers would benefit from understanding what software development entitles and adopting some of the best practices without needing to become software engineers themselves. 
+If that could be achieved, research software would be of better quality, software as a research output would be easier to maintain, which would increase the likelihood of research results being reproducible for a longer time, the productivity among researchers that continuously engage in the development of research software could be improved; and,  the time spent on directly working on research software, as a software engineer, could be increased to the benefit of the researchers themselves. 
 
-In summary, there are two situations that motived the development of this course. Firts, the need to increase the level of confidence and independece in applying version control to research sofware among researcher attending similar courses. And second, our enthusiasm to help researchers to adopt best practices in collaborative development to foster their productivity and improve the quality of research software. 
+In summary, two situations motivated the development of this course. First, there is a need to increase confidence and independence in applying version control to research software among researchers attending similar courses. Second, we are enthusiastic about helping researchers adopt best practices in collaborative development to foster their productivity and improve the quality of research software. 
 
 <h3 class="dancing">Manuel. G. García</h3>