CONTRIBUTING.html

<div class="container">
<main class="basic-inner">
<!-- Output copied to clipboard! -->
<!-- Yay, no errors, warnings, or alerts! -->
<h1>CONTRIBUTING</h1>
<h2>git structure</h2>
<p>The active branch is <code>development</code>. <code>development</code> is merged into <code>main</code> for releases. Please submit your pull requests to <code>development</code>.</p>
<h2>Repository structure</h2>
<p>The repository structure mirrors <a href="https://github.com/PASTAplus/web-x" rel="noopener noreferrer" target="_blank">web-x</a> thereby enabling developers to build, link, and preview static web pages as they will be displayed in web-x.</p>
<h2>Design and goals</h2>
<p>Content is organized into stand alone pages cross referencing each other. This modular design minimizes content duplication and maintenance. Focus on topics relevant to EDI users and not covered by other online resources (e.g. DataONE, NCEAS). Do summarize and reference other resources when relevant.</p>
<h2>General guidelines</h2>
<ul>
<li>New pages - Before adding a new page, open an issue describing the content to be developed. Maintainers (the website team) will provide feedback and suggestions for cross referencing.</li>
<li>File names - Replace spaces with dashes (e.g. new-page, new-image.png).</li>
<li>Audience - Pages should target one of the three user classes: data author, data user, or information manager.</li>
<li>Modularity - Each page should cover one topic with the goal of organizing information as modular building blocks.</li>
<li>Introductory paragraphs - Each page should begin with an introduction/overview describing why the contents of the page are important and a brief overview of the concept or process the page covers. Pages should begin with little to no prerequisite knowledge. Build prerequisite knowledge in the opening paragraphs with reference to necessary information.</li>
<li>Subsections - Use subsections to facilitate page navigation and content links.</li>
<li>Be concise and minimize jargon.</li>
</ul>
<h2>Formatting and style</h2>
<ul>
<li>Markdown - Pages should be written using the <a href="https://www.markdownguide.org/basic-syntax/" rel="noopener noreferrer" target="_blank">basic markdown syntax</a>.</li>
<li>Note: Lists (enumerated and bulleted) must be both preceded and followed by an empty line to be rendered correctly in web-x.</li>
<li>Voice - Pages should be written primarily in the first and third voice. The use of the second voice is acceptable when speaking directly to the audience (e.g. "Please contact us if you encounter an error") or in "imperative" contexts (e.g. providing step-by-step instructions).</li>
<li>Section headers - Use the gerund form a verb for the header titles (e.g. "Using Download Links", "Uploading to EDI"). Don't use a gerund in headers or subheaders if it's redundant to the higher level (Title: Publishing a data package, Header: EDI Data Portal (good), Publishing via the EDI Data Portal (bad, redundant)). A counter example would be Header: Using Box Cloud Storage, Subheader: Creating a Box File Request (good, gerund is not redundant).</li>
<li>References and links - References and links to online resources should be added as either:<ul>
<li>Hyperlinked text to the target URL</li>
<li>The wikipedia reference format (i.e. The item being referenced is super scripted in square brackets<sup>[1]</sup> and the citation is listed in a "References" section at the bottom of the page).</li>
</ul>
</li>
</ul>
<blockquote>
<p>Note, any instance of the string '' (as in the markdown file extension) will be removed in the web-x build process. To preserve '' please use '%2Emd' instead. <a href="https://github.com/PASTAplus/web-x/issues/45#issuecomment-1340255892" rel="noopener noreferrer" target="_blank">See here</a> for more details. </p>
</blockquote>
<h2>Images</h2>
<h3>Creating images</h3>
<ol>
<li>Create an image with high enough resolution so that it isn't distorted at its intended magnification and when enlarged to approximately twice its intended size. Generally, screenshots from a web browser should be taken at normal 100% magnification.</li>
<li>Trim white space from around the image.</li>
<li>Compress the image to reduce file size. Use the <a href="https://tinypng.com/" rel="noopener noreferrer" target="_blank">tinypng.com</a> web service to do this.</li>
</ol>
<h3>Adding images to markdown</h3>
<ol>
<li>Add the image file to the <code>/static/images</code> directory. </li>
<li>Reference the image from within a markdown page using HTML. There are 4 use cases:</li>
<li>Screenshots - A drop shadow is added to screenshots to help distinguish them from the body text. This is done with the <code>screen-shot</code> CSS class. Example:</li>
</ol>
<p><code>&lt;img class="screen-shot" src="/static/images/ezeml-send-revision.png" alt="Send ezEML revision" width="85%"&gt;</code></p>
<ol>
<li>Figures with captions - Example:</li>
</ol>
<blockquote>
<p>Note: This type will be deprecated in favor of option 3 below, which allows the reader to click on the image to get a full sized resolution, which can help with image viewing when they are small.</p>
</blockquote>
<p>```
 <br/>
</p><div class="figure_featured" style="width: 25%;">
<figure>
<img alt="aquatic microcosm" src="/static/images/featured_data/aquatic-microcosm.png"/>
<figcaption class="figure-caption">Fig. 1: Principal components of a Standardized Aquatic Microcosm ...</figcaption>
</figure>
</div>
<p>```</p>
<blockquote>
<p>NOTE: Featured data images to use on the website home page as well as in the grid page cards is specified by adding an <code>id="pickme"</code> parameter to the <code>&lt;img&gt;</code> tag of a featured dataset image. If none is specified, the first image of the featured data will be used. Example:
<code>&lt;div class="figure_featured" style="width: 25%;"&gt;
  &lt;figure&gt;
    &lt;img id="pickme" src="/static/images/featured_data/aquatic-microcosm.png" alt="aquatic microcosm"/&gt;
    &lt;figcaption class="figure-caption"&gt;Fig. 1: Principal components of a Standardized Aquatic Microcosm ...&lt;/figcaption&gt;
  &lt;/figure&gt;
&lt;/div&gt;</code></p>
</blockquote>
<ol>
<li>Figures with captions that enlarge on mouse click - Example:
   ```
 <br/>
<div class="figure_featured" style="width: 75%;">
<figure>
<a href="/static/images/featured_data/aquatic-microcosm.png">
<img alt="aquatic microcosm" src="/static/images/featured_data/aquatic-microcosm.png"/>
</a>
<figcaption class="figure-caption">Fig. 1: Principal components of a Standardized Aquatic Microcosm ...</figcaption>
</figure>
</div></li>
</ol>
<p>```</p>
<ol>
<li>Gallery of images for when a group of images belong together - Example:
   ```
 <br/>
<div>
<div class="gallery">
<a href="/static/images/featured_data/aquatic-microcosm.png">
<img alt="This is the image alternate title" src="/static/images/featured_data/aquatic-microcosm.png"/>
</a>
<a href="/static/images/featured_data/aquatic-microcosm.png">
<img alt="Image 2" id="pickme" src="/static/images/featured_data/aquatic-microcosm.png"/>
</a>
<a href="/static/images/featured_data/aquatic-microcosm.png">
<img alt="Image 3" src="/static/images/featured_data/aquatic-microcosm.png"/>
</a>
</div>
<div>
<p class="figure-caption" style="color: #6c757d">Scenes from the garden plots at the MSP experimental community garden: 1.) Site plots; 2.) Lysimeter sampling; 3.) Measuring harvest wet mass.</p>
</div>
</div></li>
</ol>
<p>```</p>
<ol>
<li>All other image types - Example:</li>
</ol>
<p><code>&lt;img src="/static/images/metadata-in-the-research-life-cycle.png" alt="Creating metadata in the research life cycle" width="55%"&gt;</code></p>
<ol>
<li>Resize for display in the GitHub preview. The general rule of thumb is that the image should be sized so normal body text displayed in the images should match text size on the web page. Set the image size using the <code>width</code> parameter and use a unit of <code>%</code>, meaning percent width of the page view port.</li>
</ol>
<blockquote>
<p>NOTE: A blank newline is required before and after the HTML snippet for markdown to render correctly in HTML.</p>
</blockquote>
<h2>Videos</h2>
<h3>Embedding videos</h3>
<p>Whether embedding videos within a news article or resource page, use HTML and Bootstrap following the example below:</p>
<pre><code>&lt;div class="p-2"&gt;
  &lt;div class="w-50 ratio ratio-16x9"&gt;
      &lt;iframe src="https://youtube.com/embed/Dq8ew4Iad60" title="YouTube video" allowfullscreen=""&gt;&lt;/iframe&gt;
  &lt;/div&gt;
&lt;/div&gt;
</code></pre>
<blockquote>
<p>NOTE the <code>/embed/</code> component of the YouTube video link above. You must manually insert this into a YouTube URL when creating the HTML block.</p>
</blockquote>
<h2>Terminology</h2>
<p>Consistent terminology conveys coherence and makes editing across all web pages, through search and replace methods, much simpler. Below is the current implementation of terminology throughout web pages:</p>
<ul>
<li>Capitalize EDI services and features - These are proper nouns (e.g. "EDI Data Portal")</li>
<li>"EDI Data Repository" or "EDI Repository" not "EDI Data Commons"</li>
<li>Use "research" instead of "science". Research is more diverse, science is more specific.</li>
<li>Use "data/dataset" and "metadata" before publication &amp; "data package" after publication.</li>
<li>Use "publish" over "archive" to build off the "article publishing" schema.</li>
<li>Prioritize "data publication" over "published data package"</li>
<li>Prefer "EDI Data Repository" to "PASTA" whenever possible.</li>
<li>Use "REST API" not "API".</li>
<li>Use "Information Manager (IM)" not "Data Manager (DM)"</li>
<li>Use "search data" not "find data" and "discover"data</li>
<li>"EDI Data Curation Team" or "EDI Curation Team" or "EDI curators"</li>
<li>Prefer "data file" over "data object" and "data entity" -  The latter two are non-colloquial</li>
<li>Use "EML file" when referencing the file object and "EML" or "EML metadata"  when referring to content in the file.</li>
<li>Possessive apostrophes -  don't use possessive apostrophes to denote ownership of non-living entities (e.g. "the EDI Repository's" or "a data packages'")</li>
<li>Use official terminology to establish consistency when referencing an EDI feature (e.g. "EDI Data Portal") rather than variations thereof (e.g. EDI repository interface).</li>
<li>Use "Data package landing page" or "Data package summary page" and "Full metadata page".</li>
</ul>
<h2>Format</h2>
<ul>
<li>Code - Use code highlighting when referencing code, functions, and parameters.</li>
<li>Functions - Format using <code>function_name()</code></li>
<li>Colon before a list</li>
<li>Use bold when referencing terms/items on page,  not quotes or code highlighting.</li>
<li>EML elements are listed verbatim as they appear in the schema (i.e. camel case and within "&lt;" and "&gt;" tags). Only do this in the context of EML metadata, which is typically technical documentation targeting the information manager and advanced user.</li>
<li>Use enumerated lists when describing a sequential process.</li>
<li>Be precise when linking to content in other pages - Link directly to a topic sub-section rather than just the parent page.</li>
<li>Quotes - Replace smart quotes and apostrophes with dumb quotes and apostrophes</li>
<li>Spaces - Replace all double spaces with single spaces. Single spaces after periods.</li>
</ul>
<h2>Create a News article</h2>
<p>To create a news article:
1. Copy the template below and paste into a new file in the <code>/news</code> directory.
2. The file name should follow <code>news-YYYYMMDD.XX</code>, where <code>YYYYMMDD</code> is the date the article was created, <code>XX</code> is the news article created on that date (use <code>00</code> if only one article was published on that day).
3. Update the TITLE, DATE, AUTHOR, and CONTENT placeholders.
4. Submit a pull request, or push directly to the <code>development</code> branch.
5. Notify the website team that new content has been added and they will finalize the upload.</p>
<pre><code># News

## ADD TITLE HERE

ADD DATE HERE (e.g. April 20, 2022)

ADD ARTICLE AUTHOR HERE

### Description

ADD CONTENT HERE

&lt;!-- News --&gt;
</code></pre>
<h2>Create a Featured Data article</h2>
<p>To create a new featured data article:
1. Create a markdown file for the new featured data article in the <code>/featured</code> directory. Name it following the pattern <code>featured-ID</code> where <code>ID</code> uniquely identifies the article.
2. Copy the template below and paste into the new file.
3. Update the <code>TITLE</code>, <code>DATE</code>, <code>AUTHOR</code>, <code>CITATION</code>, and <code>CONTENT</code> placeholders. Note, the final date of publication will be added later. Do not add a date here or else the article will be listed in the featured data article index.
4. Compress article images using a service like <a href="https://tinypng.com/" rel="noopener noreferrer" target="_blank">tinypng.com</a>. Add images to the <code>/static/images/featured_data</code> directory and reference from within display type HTML blocks (<code>gallery</code> and/or <code>figure_featured</code>; see below). Replicate these HTML blocks as needed.
5. Commit changes to the development branch and push to the content-x GitHub. Notify the website team that new content has been added, they will integrate your work into the development side of the web-x server (i.e. web-d) and will send you a link to the article proof. Note, the article will only be referencable from the link since it is unattached to other website pages. This keeps the WIP hidden from public view. 
6. Send the article author a proof for review and comment. Apply any requested changes and repeat step 5 above.
7. When ready to publish, update the file name to follow the pattern <code>featured-YYYYMMDD.XX</code>, where <code>YYYYMMDD</code> is the date the article was created, <code>XX</code> is the news article created on that date (use <code>00</code> if only one article was published on that day). Repeat step 5 above.
8. Notify article authors of the publication.</p>
<pre><code># Featured Data

## TITLE

DATE (e.g. March 1, 2021)

AUTHOR

### Citation

CITATION

### Description

CONTENT

&lt;!-- Images used in articles follow the HTML format below. Adjust the "width" parameter to resize. 
Identify the primary image to use with the featured data display on web-x home page and on the featured 
data grid page by adding an id="pickme" parameter to the HTML, if not specified, the first image of the page will be used. Note, there are two ways to display images.--&gt;

&lt;div class="figure_featured" style="width: 75%;"&gt;
   &lt;figure&gt;
     &lt;a href="/static/images/featured_data/FILE.EXT"&gt;
       &lt;img src="/static/images/featured_data/FILE.EXT" alt="ADD DESCRIPTION OF IMAGE"/&gt;
     &lt;/a&gt;
     &lt;figcaption class="figure-caption"&gt;ADD CAPTION HERE&lt;/figcaption&gt;
   &lt;/figure&gt;
&lt;/div&gt;

&lt;div&gt;
  &lt;div class="gallery"&gt;
    &lt;a href="/static/images/featured_data/IMAGE.EXT"&gt;
      &lt;img src="/static/images/featured_data/IMAGE.EXT" alt="ADD DESCRIPTION OF IMAGE"&gt;
    &lt;/a&gt;
    &lt;a href="/static/images/featured_data/IMAGE.EXT"&gt;
      &lt;img src="/static/images/featured_data/IMAGE.EXT" alt="ADD DESCRIPTION OF IMAGE"&gt;
    &lt;/a&gt;
    &lt;a href="/static/images/featured_data/IMAGE.EXT"&gt;
      &lt;img src="/static/images/featured_data/IMAGE.EXT" alt="ADD DESCRIPTION OF IMAGE"&gt;
    &lt;/a&gt;
  &lt;/div&gt;
  &lt;div&gt;
    &lt;p class="figure-caption" style="color: #6c757d"&gt;ADD CAPTION HERE FOR ALL IMAGES REFERENCED ABOVE&lt;/p&gt;
  &lt;/div&gt;
&lt;/div&gt;


#### Data sources for the database include

### References

### [All featured data contributions](/featured/featured-grid)

</code></pre>
<h2>Create a Webinar article</h2>
<p>To create a webinar article:
1. Copy the template below and paste into a new file in the <code>/webinars</code> directory.
2. The file name should follow <code>webinars-YYYYMMDD.XX</code>, where <code>YYYYMMDD</code> is the date the article was created, <code>XX</code> is the news article created on that date (use <code>00</code> if only one article was published on that day).
3. Update the TITLE, DATE, AUTHOR, and CONTENT placeholders.
4. Commit changes and push to the content-x GitHub.
5. Notify the website team that new content has been added and they will integrate your work into the website.</p>
<pre><code># Webinar

## ADD TITLE HERE

ADD DATE HERE (e.g.October 18, 2022)

### Description

ADD CONTENT HERE

### Speakers

ADD SPEAKERS HERE

### Recording

EMBED YOUTUBE VIDEO RECORDING HERE

&lt;!-- Webinars --&gt;
</code></pre>
</main>
</div>