version 1

Author: w. Patrick Gale

CHANGELOG.md

@@ -5,16 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.0.2] - future
 
-- [ ] add Algolia search once the site is production ready
-- [ ] `cmfcmf/docusaurus-search-local` search plugin needs better configuration
-- [ ] local search linking to pages such as `https://jocoknow.vercel.app/docs/jocoknow-extras/translate-your-site/docs/jocoknow-extras/translate-your-site#translate-a-doc` which do not exist
-- [ ] add resources for developing data management plan (https://dmponline.dcc.ac.uk/) and data curation logs
-- [ ] add a template for logging data curation steps
-- [ ] need to add 'levels' to the docs/intro document and make it more user-friendly
-- [ ] update `intro` document with links and more information
-- [ ] write instructions for a curation log example using JSON and code to parse the file into Markdown; include methods for adding ToDo items to the log to help encourage users to make use of the log; add ability to include question or checklist types to a curation task **IMPORTANT**
+## [1.0.0] - Sept. 20, 2024
+
+- [x] update `intro` document with links and more information
+- [x] removed default Docusaurus styling
 - [x] create python packages for handling basic API functions
 - [x] added cheerio resolutions to the package.json file to correct an issue with local search
 - [x] adding additional documentation for a data curation checklist and steps to help automate a curation log
@@ -26,4 +21,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [x] updated Docusaurus to version 3.5.2
 - [x] testing orama search plugin, but both the local and cloud version have an error needing to be fixed in https://github.com/askorama/orama/issues/728
 - [x] testing DocSearch crawler https://docsearch.algolia.com/docs/legacy/run-your-own/#run-the-crawl-from-the-docker-image and setting up an .env.prod set of environment variables, but it keeps throwing `Unreachable hosts` error
-- [x] adding a basic `cmfcmf/docusaurus-search-local` search plugin (needs configuration changes but is a good starter)
+- [x] adding a basic `cmfcmf/docusaurus-search-local` search plugin (needs configuration changes but is a good starter search tool)
+
+## [x.x.x] - future ideas
+
+- [ ] write instructions on how to link this documentation site builder with the Jupyter notebooks used for dataset curation to publish the curation logs to this site under dataset specific directories/pages (using shutil commands to copy files from the notebook directories to this site builder)
+- [ ] add Algolia search once the site is production ready and write up a document regarding how users can best search for data
+- [ ] write a document which contains the code and resources to build a curation log generator and how it compares to the curation log for https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/SKP9IB
+- [ ] `cmfcmf/docusaurus-search-local` search plugin needs better configuration
+- [ ] local search linking to pages such as `https://jocoknow.vercel.app/docs/jocoknow-extras/translate-your-site/docs/jocoknow-extras/translate-your-site#translate-a-doc` which do not exist
+- [ ] add resources for developing data management plan (https://dmponline.dcc.ac.uk/) and data curation logs
+- [ ] add a template for logging data curation steps
+- [ ] write instructions for a curation log example using JSON and code to parse the file into Markdown; include methods for adding ToDo items to the log to help encourage users to make use of the log; add ability to include question or checklist types to a curation task **IMPORTANT**
+- [ ] try to query the Dataverse API to retrieve a list of datasets to help autogenerate a dataset listing README file that links to the individual README files of each dataset (remove dataset category JSON and replace with this)

README.md

@@ -1,6 +1,6 @@
 # About this code
 
-This repository was started in August of 2024 and uses [Docusaurus 3](https://docusaurus.io), a modern static website generator. The idea behind the repository is to provide an knowledgebase guide into understanding and working with the JoCo publicly available data.
+This repository was started in August of 2024 and uses [Docusaurus 3](https://docusaurus.io), a modern static website generator. The idea behind the repository is to provide a knowledgebase guide into understanding and working with the JoCo publicly available data.
 
 ## Why Docusaurus
 
@@ -9,21 +9,22 @@ The reason for Docusaurus is it is a CMS framework with integrations for things
 Other benefits are:
 
 - The Docusaurus framework automatically checks for broken links in your documents when you build the code (whether you are building locally or letting Vercel build for you). This is great for quality assurance.
-- Looking good from the start, means a framework that has been designed by professional graphic artists for accessibility and out-of-the-box visual appeal. So you can simply focus on content and not building a site from scratch.
+- Looking good from the start, means a framework that has been designed by professional graphic artists for accessibility and out-of-the-box visual appeal. You can simply focus on content and not c creating a site from scratch.
 
 ## Using this code on Vercel
 
-The easiest way use this code (for your own project or to help contribute to this documentation) is to fork this repository in GitHub then log into Vercel.com and create a new project using your forked repo. Vercel can be used as a cloud testing environment, to help you avoid the need to setup NodeJs and NPM on your local computer (but you could do that as well). Vercel will build from your GitHub code repository and setup a test site so you could simply make changes to your forked repository code in GitHub.com, and see the changes in Vercel as you make code updates. 
+The easiest way to use this code (for your own project or to help contribute to this documentation) is to fork this repository in GitHub then log into Vercel.com and create a new project using your forked repo. You can use Vercel as a cloud testing environment, to help you avoid the need to setup NodeJs and NPM on your local computer (but you could do that as well). Vercel will build from your GitHub code repository and set up a test site. This allows you to simply make changes to your forked repository code in GitHub.com, and see the changes in Vercel as you make code updates. 
 
-Note, some of the application settings are set as environment variables. The `.env.example` file contains place-holder values for the environment. These variables will need to be added to your Vercel project since you do not want sensitive environment API keys or passwords published/embedded in your repository code. Once you have the code deployed to Vercel from GitHub, a link to your test site on Vercel will added to your main repository page on GitHub.
+Note, several application settings are set as environment variables. The `.env.example` file contains place-holder values for the environment. You will need to add these variables to your Vercel project since you do not want sensitive environment API keys or passwords published/embedded in your repository code. After deploying the code to Vercel from GitHub, a link to your test site on Vercel will be included on your main repository page on GitHub.
 
 ## Using the code locally
 
-See Docusaurus documentation for this. It is not recommended. Try using StackBlitz (which is free but slow to rebuild the site) or some other virtual service first, to save you the headache of installing dependencies on your computer.
-
-
+See Docusaurus documentation for this. Try using StackBlitz as an alternative (which is free but slow to rebuild the site) or some other virtual service first, to save you the headache of installing dependencies on your computer.
+For me, I open a WSL command and paste the following command to ensure I am in the correct directory before I try to run Docusausus:
 `cd "/mnt/c/Users/pgale/University of North Carolina at Chapel Hill/TarcStudyDataRepository - Files/DataPull/364-dp/Note3/jocoknow"`
 
+**Technical Note: If you are testing Docusaurus locally and the command line that serves the Docusaurus site is closed unexpectedly, it is best to simply log out of the computer and log back so you can start the site using a new instance (since `port in use` issues will be difficult to resolve otherwise).**
+
 ## Update or add packages
 
 Use Yarn via https://yarnpkg.com/getting-started/install. When adding something like a search module to the package.json script, run `yarn up` to update the packages or `yarn add` to add a package.
@@ -34,12 +35,13 @@ To run the build first run `yarn build` then `yarn run serve` (this is ideal bec
 
 Review the documentation at https://docsearch.algolia.com/docs/legacy/run-your-own/ or https://docsearch.algolia.com/docs/legacy/config-file
 
-- First we need to log into Algolia and select or create the application we want to use (which in this case is JoCoKnow)
+- Log into Algolia and select or create the application we want to use (which in this case is JoCoKnow)
 - Next we need to create the index for this application and give the index a name
 - Next add an API needs the ACL addObject, editSettings and deleteIndex.
 
 the `Search-Only API Key` and copy that to our environment file.
 
-
 Here we will use the `.env.prod` file to define our APPLICATION_ID and API_KEY
 `docker run -it --env-file=.env.prod -e "CONFIG=$(cat jocoknow.config.json | jq -r tostring)" algolia/docsearch-scraper`
+
+

docs/contact.md

@@ -4,4 +4,8 @@ sidebar_position: 2
 
 # Contact Us
 
-If you have questions for us regarding the JoCo data or would like to leave us suggestions and feedback, please use the following form: [https://unc.az1.qualtrics.com/jfe/form/SV_3ruQfOlS87zcyZE](https://unc.az1.qualtrics.com/jfe/form/SV_3ruQfOlS87zcyZE?RuPath=https://jocoknow.vercel.app/).
+Use the form below to submit any questions you may have regarding the JoCo data or would like to leave us suggestions and feedback.
+
+:::info[Get in touch]
+### [https://unc.az1.qualtrics.com/jfe/form/SV_3ruQfOlS87zcyZE](https://unc.az1.qualtrics.com/jfe/form/SV_3ruQfOlS87zcyZE?RuPath=https://jocoknow.vercel.app/)
+:::

docs/curation-tools/CURATED-checklist.md

@@ -109,12 +109,13 @@ In this step, examine the dataset closely to understand what it is, how the file
 - [ ] Examine files, organization, and documentation more thoroughly. 
   - [ ] Are there changes that could enhance the dataset? 
   - [ ] Are there missing data? 
-  - [ ] Could a user with similar qualifications to the author's understand and reuse these data and reproduce the results? Are the data, documentation and/or metadata presented in a way that aids in interpretation? (e.g., [README Example](https://deepblue.lib.umich.edu/data/Deep\_Blue\_Data\_Example\_Readme.txt)) 
+  - [ ] Could a user with similar qualifications to the author's understand and reuse these data and reproduce the results? 
+  - [ ] Are the data, documentation and/or metadata presented in a way that aids in interpretation? (e.g., [README Example](https://deepblue.lib.umich.edu/data/Deep\_Blue\_Data\_Example\_Readme.txt)) 
 - [ ] Record all questions and concerns in Curation Log.  
 
 *Tasks vary based on file formats and subject domain. Sample tasks based on format:* 
 
-**Tabular Data (e.g, Microsoft Excel) Questions:**
+**Tabular Data (e.g. Microsoft Excel) Questions:**
 
 - [ ] Check the organization of the data–is it well-structured? 
 - [ ] Are headers/codes clearly defined? 
@@ -133,8 +134,8 @@ In this step, examine the dataset closely to understand what it is, how the file
 - [ ] Is the code commented, i.e., did the author provide descriptive information on sections of code? 
 - [ ] Is data for input missing? Are environmental conditions and parameters noted? Is it clear which language(s) and version(s) are used? 
 - [ ] Does the code use absolute paths or relative paths? If absolute paths, is this documented in the README? 
-- [ ] Are packages or additional libraries used? Is so, is this noted with clear use instructions?  
-- [ ] Are any data organized consistently for access by the code? 
+- [ ] Are packages or additional libraries used? I so, is this noted with clear use instructions?  
+- [ ] Is data organized consistently for access by the code? 
 - [ ] Is there an indication of whether the depositor intends users to be able to run the code and reproduce results, or just see the process used?  
 
 To view additional UNDERSTAND steps based on format, view the following primers:
@@ -238,7 +239,7 @@ In this step we ensure metadata conforms to repository and/or appropriate discip
   - [ ] Add subject terms 
 - [ ] Ensure keywords are sufficient and representative 
 - [ ] Record all changes in the Curation Log 
-- [ ] Provide suggestions to improve accessibility of content (e.g., alt-text or additional descriptions; color contrast; etc.)
+- [ ] Provide suggestions to improve accessibility of content (e.g., alt-text or additional descriptions, color contrast, etc.)
 
 :::
 
@@ -249,7 +250,7 @@ In this step we ensure metadata conforms to repository and/or appropriate discip
 In this step, consider the file formats in the dataset to make them more interoperable, reusable, preservation friendly, and non-proprietary when possible.<sup>[1](#footnote-1)</sup> Common TRANSFORM steps include: 
 
 - Identify specialized file formats and their restrictions (e.g., Is the software freely available? If so, link to it or archive it alongside the data)  
-- Propose open source or more reusable formats when appropriate 
+- Propose open-source or more reusable formats when appropriate 
 - Retain original file formats 
 
 #### Footnote 1
@@ -267,7 +268,7 @@ In this step, consider the file formats in the dataset to make them more interop
   - [ ] If not, recommend conversion 
   - [ ] Retain original formats 
 - [ ] Check whether software needed is readily available 
-  - [ ] Suggest open source options, if applicable and appropriate 
+  - [ ] Suggest open-source options, if applicable and appropriate 
   - [ ] Ensure software and software version is documented  
 - [ ] Convert any data visualization(s) that are not accessible (e.g., R [visualizations](https://github.com/DataCurationNetwork/data-primers/blob/master/R%20Data%20Curation%20Primer/R-data-curation-primer.md#accessibility-considerations), which need to be converted for screen reader use, or visualizations that do not meet color contrast guidelines) Reorganize files as appropriate  
 - [ ] Standardize file names  
@@ -294,7 +295,7 @@ In this step, review the dataset and companion data record against international
 ### Key Ethical Considerations
 
 - Final review--remember it is not too late to surface any ethical concerns. 
-- Verify the words/language being used are not racist/harmful. 
+- Verify you are not using racist/harmful words/language. 
 - Remind the submitter of their responsibility if they choose to ignore requests for de-identification or similar concerns.
 
 ### Essential Tasks

docs/curation-tools/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Data Curation Tools",
-  "position": 4,
+  "position": 6,
   "link": {
     "type": "generated-index",
     "description": "We want to help you manage your data as well as we have, by providing you with the toolset we used to manage this project."

docs/curation-tools/curation_template.md

@@ -89,12 +89,13 @@ In this step, examine the dataset closely to understand what it is, how the file
 - [ ] Examine files, organization, and documentation more thoroughly. 
   - [ ] Are there changes that could enhance the dataset? 
   - [ ] Are there missing data? 
-  - [ ] Could a user with similar qualifications to the author's understand and reuse these data and reproduce the results? Are the data, documentation and/or metadata presented in a way that aids in interpretation? (e.g., [README Example](https://deepblue.lib.umich.edu/data/Deep\_Blue\_Data\_Example\_Readme.txt)) 
+  - [ ] Could a user with similar qualifications to the author's understand and reuse these data and reproduce the results? 
+  - [ ] Are the data, documentation and/or metadata presented in a way that aids in interpretation? (e.g., [README Example](https://deepblue.lib.umich.edu/data/Deep\_Blue\_Data\_Example\_Readme.txt)) 
 - [ ] Record all questions and concerns in Curation Log.  
 
 *Tasks vary based on file formats and subject domain. Sample tasks based on format:* 
 
-**Tabular Data (e.g, Microsoft Excel) Questions:**
+**Tabular Data (e.g. Microsoft Excel) Questions:**
 
 - [ ] Check the organization of the data–is it well-structured? 
 - [ ] Are headers/codes clearly defined? 
@@ -113,7 +114,7 @@ In this step, examine the dataset closely to understand what it is, how the file
 - [ ] Is the code commented, i.e., did the author provide descriptive information on sections of code? 
 - [ ] Is data for input missing? Are environmental conditions and parameters noted? Is it clear which language(s) and version(s) are used? 
 - [ ] Does the code use absolute paths or relative paths? If absolute paths, is this documented in the README? 
-- [ ] Are packages or additional libraries used? Is so, is this noted with clear use instructions?  
+- [ ] Are packages or additional libraries used? If so, is this noted with clear use instructions?  
 - [ ] Are any data organized consistently for access by the code? 
 - [ ] Is there an indication of whether the depositor intends users to be able to run the code and reproduce results, or just see the process used?  
 
@@ -229,7 +230,7 @@ In this step we ensure metadata conforms to repository and/or appropriate discip
 In this step, consider the file formats in the dataset to make them more interoperable, reusable, preservation friendly, and non-proprietary when possible.<sup>[1](#footnote-1)</sup> Common TRANSFORM steps include: 
 
 - Identify specialized file formats and their restrictions (e.g., Is the software freely available? If so, link to it or archive it alongside the data)  
-- Propose open source or more reusable formats when appropriate 
+- Propose open-source or more reusable formats when appropriate 
 - Retain original file formats 
 
 #### Footnote 1
@@ -247,7 +248,7 @@ In this step, consider the file formats in the dataset to make them more interop
   - [ ] If not, recommend conversion 
   - [ ] Retain original formats 
 - [ ] Check whether software needed is readily available 
-  - [ ] Suggest open source options, if applicable and appropriate 
+  - [ ] Suggest open-source options, if applicable and appropriate 
   - [ ] Ensure software and software version is documented  
 - [ ] Convert any data visualization(s) that are not accessible (e.g., R [visualizations](https://github.com/DataCurationNetwork/data-primers/blob/master/R%20Data%20Curation%20Primer/R-data-curation-primer.md#accessibility-considerations), which need to be converted for screen reader use, or visualizations that do not meet color contrast guidelines) Reorganize files as appropriate  
 - [ ] Standardize file names  
@@ -274,7 +275,7 @@ In this step, review the dataset and companion data record against international
 ### Key Ethical Considerations
 
 - Final review--remember it is not too late to surface any ethical concerns. 
-- Verify the words/language being used are not racist/harmful. 
+- Verify you are not using racist/harmful words/language. 
 - Remind the submitter of their responsibility if they choose to ignore requests for de-identification or similar concerns.
 
 ### Essential Tasks