Update portfolio.md

rs-impact/portfolio.md

@@ -5,23 +5,29 @@ parent: Research Software and Research Impact
 nav_order: 3
 ---
 
-## Building Your Researcher Portfolio with ORCID ID
+## Building Your Researcher Portfolio with ORCID
 
-DOIs and ORCID IDs work together to enhance the credibility, visibility, and attribution of scholarly research. DOIs provide unique identifiers for individual research outputs, while ORCID IDs provide unique identifiers for researchers themselves. By linking the two, your scholarly works can be accurately attributed to you, facilitating better tracking of research impact and establishing reliable connections between researchers and their contributions. In the upcoming sections, we will explore the steps to connect your research software development with DOI and ORCID ID record.  
+DOIs and ORCIDs work together to enhance the credibility, visibility, and attribution of scholarly research. DOIs provide unique identifiers for individual research outputs, while ORCIDs provide unique identifiers for researchers themselves. By linking the two, your scholarly works can be accurately attributed to you, facilitating better tracking of research impact and establishing reliable connections between researchers and their contributions. In the upcoming section we will explore the steps to connect your research software development with DOI and ORCID persistent identifiers to create a research profile.  
 
-### Generate DOI for Your Research Software
+### Generate a DOI for Your Research Software
 
-Assuming you have deposited and publish your software source code on GitHub with a license. Now you can index your software source code with DOI using [Zenodo.org](https://zenodo.org/). Zenodo is a free and open-access research data repository and publishing platform that facilitates the sharing, archiving, and dissemination of research outputs. It is an initiative developed and operated by CERN (European Organization for Nuclear Research) and is part of the European OpenAIRE project.  
+To generate a DOI for software, we will use the public and popular [Zenodo](https://about.zenodo.org/) repository. Zenodo is a free, open-access research data repository and publishing platform that facilitates the sharing, archiving and dissemination of research outputs. It is an initiative developed and operated by CERN (European Organization for Nuclear Research) and is part of the European OpenAIRE project.  
 
-First, create a Zenodo account, you may use a email & password authentication method or Single-Sign On with GitHub or ORCID ID.  
+In this example, we will demonstrate how to create a repository on Zenodo directly from your _public_ repository on GitHub. (You cannot create a DOI to a private repository.) Per your Software Management Plan, this repository should include your software license as well as licenses for any software libraries included.
+
+It is worth noting here, again, that while GitHub is a good version control system for managing software versions, performing collaborative development, it is not considered a persistent repository for software. There are too many reaosons why a git repository might have its location or reference change. We use Zenodo in this example as such a persistent software repository, which is necessary for identifiers like DOIs to be persistent.
+
+### Steps to Generate a DOI for Your Research Software
+
+First, create a Zenodo account. You may use an email + password authentication method or single sign-on with GitHub or ORCID accounts.  
 
 ![zenodo-sso](assets/img/zenodo-sso.png)  
 
-Once you have created a Zenodo account, click the dropdown menu which contains your Zenodo registration email and select GitHub.  
+Once you have created and logged into your Zenodo account, click the drop-down menu (in the banner, top-right), which contains your Zenodo registration email, and select GitHub.  
 
 ![zenodo-1](assets/img/zenodo-1.png)  
 
-Follow the instructions provided to link your GitHub account with Zenodo. And once you have linked your GitHub account with Zenodo. You will see all your public repositories from Zenodo side. Scroll to the repository you want to index and toggle the switch box next to it to turn on automatic preservation.  
+Follow the instructions provided to link your GitHub account with Zenodo. Once you have linked your GitHub account with Zenodo, you will see all your public repositories from the Zenodo side. In Zenodo, scroll to the repository you want to index and toggle the switch box next to it to turn on automatic preservation. In the screenshots below we demonstrate these actions on the software repository `quantum-stable-matching`.
 
 ![zenodo-2](assets/img/zenodo-2.png)  
 
@@ -31,15 +37,17 @@ Then go to the GitHub repository and [create a release](https://docs.github.com/
 
 ![zenodo-3](assets/img/zenodo-3.png)  
 
-It will take approximately 1 hour for Zenodo to generate a DOI and about a day for the DOI to be effective on [doi.org](https://www.doi.org/).  
+It will take approximately 1 hour for Zenodo to generate a DOI and about a day for the DOI to be effective on [doi.org](https://www.doi.org/) through their respective background automation processes.
 
 ![zenodo-4](assets/img/zenodo-4.png)
 
-### Adding Your Research Software to Your ORCID ID Record
+### Adding Your Research Software to Your ORCID Record
 
-Now that you have a DOI for your research software project, it is time to add it to your ORCID ID record.  
+Now that you have a DOI for your research software project, it is time to add it to your ORCID profile.  
 
-Login your ORCID ID record. Go to "Works" and click the "Add" button. Select "Add DOI". Enter the DOI of your project and then click "Retrieve work details from DOI".  
+If you do not yet have an ORCID record, [Register on ORCID](https://orcid.org/register) to create one.
+
+Log in to your ORCID record. Go to "Works" and click the "Add" button. Select "Add DOI". Enter the DOI of your project and then click "Retrieve work details from DOI".  
 
 ![orcid-1](assets/img/orcid-1.png)  
 ![orcid-2](assets/img/orcid-2.png)  
@@ -48,6 +56,8 @@ Edit the work details and the click "Add this work to your ORCID record".
 
 ![orcid-3](assets/img/orcid-3.png)  
 
-You will see the new entry in the ORCID ID work record.  
+You will see the new entry in the ORCID work record.  
 
 ![orcid-4](assets/img/orcid-4.png)  
+
+At this point you will have deposited a persistent copy of your software release on Zenodo, created a DOI for this software project and release, and linked this work with your ORCID profile.