Merge pull request #1835 from datadryad/readme-examples

Link to README examples in README wizard
datadryad · Sep 10, 2024 · bb97aa9 · bb97aa9
2 parents fd61bcc + a41a4d2
commit bb97aa9
Show file tree

Hide file tree

Showing 3 changed files with 89 additions and 8 deletions.
diff --git a/app/assets/stylesheets/scss/_upload.scss b/app/assets/stylesheets/scss/_upload.scss
@@ -75,4 +75,12 @@
 }
 .readme-buttons {
   justify-content: center;
+}
+
+.readme-examples {
+  list-style-type: none;
+  padding-left: 0;
+  i {
+    margin-right: .5ch;
+  }
 }
diff --git a/app/javascript/react/components/ReadMeWizard/ReadMeSteps.jsx b/app/javascript/react/components/ReadMeWizard/ReadMeSteps.jsx
@@ -40,10 +40,44 @@ export default function ReadMeSteps({
         </ul>
       </>,
       content: content.step2 || formatList(fileList),
+      examples: [
+        {
+          key: 'nzs7h44xg',
+          example:
+        <><a href="https://datadryad.org/stash/dataset/doi:10.5061/dryad.nzs7h44xg#readme" target="_blank" rel="noreferrer"><i className="fa fa-right-to-bracket" aria-hidden="true" />View example README<span className="screen-reader-only"> (opens in new window)</span></a> describing data of several file types, including genomic data
+        </>,
+        },
+        {
+          key: 'rr4xgxdg6',
+          example:
+        <><a href="https://datadryad.org/stash/dataset/doi:10.5061/dryad.rr4xgxdg6#readme" target="_blank" rel="noreferrer"><i className="fa fa-right-to-bracket" aria-hidden="true" />View example README<span className="screen-reader-only"> (opens in new window)</span></a> with a content section describing MATLAB files
+        </>,
+        },
+        {
+          key: '18931zd25',
+          example:
+        <><a href="https://datadryad.org/stash/dataset/doi:10.5061/dryad.18931zd25#readme" target="_blank" rel="noreferrer"><i className="fa fa-right-to-bracket" aria-hidden="true" />View example README<span className="screen-reader-only"> (opens in new window)</span></a> with good detail for genomic VCF files
+        </>,
+        },
+      ],
     },
     3: {
       desc: <p>What free or open software is needed to view your data? Describe the software, including versions and loaded packages that you used to run files, and the workflow that you used if the relationship of files to software is not clear. If code or scripts are included with your submission, describe them here.</p>,
       content: content.step3 || '',
+      examples: [
+        {
+          key: 'jdfn2z3j3',
+          example:
+        <><a href="https://datadryad.org/stash/dataset/doi:10.5061/dryad.jdfn2z3j3#readme" target="_blank" rel="noreferrer"><i className="fa fa-right-to-bracket" aria-hidden="true" />View example README<span className="screen-reader-only"> (opens in new window)</span></a> containing excellent information on how to set up, access, and run neural network deep learning code
+        </>,
+        },
+        {
+          key: 'h70rxwdq5',
+          example:
+        <><a href="https://datadryad.org/stash/dataset/doi:10.5061/dryad.h70rxwdq5#readme" target="_blank" rel="noreferrer"><i className="fa fa-right-to-bracket" aria-hidden="true" />View example README<span className="screen-reader-only"> (opens in new window)</span></a> with a detailed Recommended Software section
+        </>,
+        },
+      ],
     },
     4: {
       desc: <p>If applicable, provide links to other publicly accessible locations of the data. If your data was derived from another source(s), list the source(s) and include license information.</p>,
@@ -62,7 +96,18 @@ export default function ReadMeSteps({
         ))}
       </div>
       <h2><label htmlFor="readme_step_editor">{secTitles[step - 1]}</label></h2>
-      <div>{sections[step].desc}</div>
+      {Object.hasOwn(sections[step], 'examples') ? (
+        <div className="readme-columns-final">
+          <div>{sections[step].desc}</div>
+          <div style={{padding: '1.5rem'}}>
+            <ul className="readme-examples">
+              {sections[step].examples.map((ex) => <li key={ex.key}>{ex.example}</li>)}
+            </ul>
+          </div>
+        </div>
+      ) : (
+        <div>{sections[step].desc}</div>
+      )}
       <MarkdownEditor
         id="readme_step_editor"
         {...(step === 1 ? {initialValue: '', replaceValue: sections[step].content} : {initialValue: sections[step].content})}

diff --git a/app/javascript/react/containers/ReadMeWizard.jsx b/app/javascript/react/containers/ReadMeWizard.jsx
@@ -168,16 +168,13 @@ export default function ReadMe({
         <div style={{height: '100%'}}>
           <div style={{maxWidth: '90ch'}}>
             <p style={{marginTop: 0}}>
-              Your Dryad submission must be accompanied by a README file, to help others use and understand your
+              Your Dryad submission must be accompanied by a{' '}
+              <a href="/stash/best_practices#describe-your-dataset-in-a-readme-file" target="_blank">
+                README file<span className="screen-reader-only"> (opens in new window)</span>
+              </a>, to help others use and understand your
               dataset. It should contain the details needed to interpret and reuse your data, including abbreviations
               and codes, file descriptions, and information about any necessary software.
             </p>
-            <p style={{textAlign: 'center'}}>
-              <a href="/stash/best_practices#describe-your-dataset-in-a-readme-file" target="_blank">
-                <i className="far fa-file-lines" aria-hidden="true" style={{marginRight: '.5ch'}} />Learn about README files
-                <span className="screen-reader-only"> (opens in new window)</span>
-              </a>
-            </p>
           </div>
           <div className="readme-columns">
             <div>
@@ -195,6 +192,37 @@ export default function ReadMe({
               <ReadMeImport setValue={setReplaceValue} />
             </div>
           </div>
+          <div style={{maxWidth: '90ch', marginBottom: '2rem'}}>
+            <h2>Need an example?</h2>
+            <p>Here are some outstanding READMEs from Dryad submissions, which show the following:</p>
+            <ul className="readme-examples" style={{paddingLeft: '2ch'}}>
+              <li>
+                <a href="https://datadryad.org/stash/dataset/doi:10.5061/dryad.h70rxwdq5#readme" target="_blank" rel="noreferrer"><i className="fa fa-right-to-bracket" aria-hidden="true" />
+                  Chromatographic and mass spectrometric analysis data<span className="screen-reader-only"> (opens in new window)</span>
+                </a>
+              </li>
+              <li>
+                <a href="https://datadryad.org/stash/dataset/doi:10.5061/dryad.rr4xgxdg6#readme" target="_blank" rel="noreferrer"><i className="fa fa-right-to-bracket" aria-hidden="true" />
+                MATLAB files<span className="screen-reader-only"> (opens in new window)</span>
+                </a>
+              </li>
+              <li>
+                <a href="https://datadryad.org/stash/dataset/doi:10.5061/dryad.nzs7h44xg#readme" target="_blank" rel="noreferrer"><i className="fa fa-right-to-bracket" aria-hidden="true" />
+                Genomic data<span className="screen-reader-only"> (opens in new window)</span>
+                </a>
+              </li>
+              <li>
+                <a href="https://datadryad.org/stash/dataset/doi:10.5061/dryad.jdfn2z3j3#readme" target="_blank" rel="noreferrer"><i className="fa fa-right-to-bracket" aria-hidden="true" />
+                Neural network deep learning code<span className="screen-reader-only"> (opens in new window)</span>
+                </a>
+              </li>
+              <li>
+                <a href="https://datadryad.org/stash/dataset/doi:10.5061/dryad.18931zd25#readme" target="_blank" rel="noreferrer"><i className="fa fa-right-to-bracket" aria-hidden="true" />
+                Genomic VCF and companion scripts<span className="screen-reader-only"> (opens in new window)</span>
+                </a>
+              </li>
+            </ul>
+          </div>
         </div>
       );
     }