Skip to content

Latest commit

 

History

History
303 lines (204 loc) · 9.39 KB

index.rst

File metadata and controls

303 lines (204 loc) · 9.39 KB
Raw

|CyVerse_logo|_

|Home_Icon|_ Learning Center Home

Creating Documentation in the CyVerse Learning Center

Goal

All users are invited to contribute to CyVerse documentation, from fixing a typo to contributing a new tutorial. This quickstart will get you through the initial steps of your contribution.

.. toctree::
        :maxdepth: 2

        Quickstart home <self>
        Example ReStructured Text <example_directives_delete.rst>

Prerequisites

Downloads, access, and services

In order to complete this tutorial you will need access to the following services/software

Prerequisite Preparation/Notes Link/Download
CyVerse account You will need a CyVerse account to complete this exercise |CyVerse User Portal|
GitHub account You will need a GitHub account to complete this exercise GitHub
A text editor You will need a text editor (word processing programs like Microsoft Word introduce formatting errors and are not acceptable). We recommend a free editor like Atom Atom

Platform(s)

We will use the following platform(s):

Platform Interface Link Platform Documentation
CyVerse Learning Center Github repository and ReadTheDocs |CyVerse Learning Center| This document
GitHub Online repository management GitHub GitHub Guide
Read the Docs Online documentation platform Read the Docs Read the Docs Docs

A. Improving Existing Documentation in the CyVerse Learning Center

All CyVerse documentation is a community effort. You can contribute in several ways including:

  • Reporting typos or grammatical mistakes
  • Identifying instructions that are out-of-date, unclear, or wrong
  • Suggesting other improvements

You can help fix these by reporting a documentation issue. You can click the |Intercom| icon on the lower-left of your screen and send us a message. Or, if you are familiar with GitHub you can either file and issue or submit a pull request. Creating issues just requires a few seconds of your time, so we will cover that here:

Creating an issue on GitHub

  1. At the bottom of the documentation there should be a link called Github Repo Link or Repo Link. Click this link to go to the GitHub Repository (the online location of the documentation text).

  2. On the GitHub site, click the "Issues" tab near the top of the screen.

    issues

    If the issue list is empty Click "New Issue"; You may need to login to your GitHub account. Give your issue a descriptive title and a comment. Once you are done, click "Submit new issue." You will receive notifications (unless you opt out) from GitHub on the status of your issue.

    If the issue list is contains issues If possible, check to see that the issue you identified is not in the current list. If your issue already exists, you may still wish to leave a comment. If you think your issue is new, click "New Issue"; you may need to login to your GitHub account. Give your issue a descriptive title and then leave a comment. Once you are done, click "Submit new issue." You will receive notifications (unless you opt out) from GitHub on the status of your issue.

B. Creating New Documentation in the CyVerse Learning Center

These instructions assume some familiarity with GitHub. If you are not comfortable with GitHub, but have a documentation contribution to make, please email us with your ideas or content: Tutorials@CyVerse.org.

Tip

Every documentation piece is create from a template in a GitHub repository. There are some template-specific instructions in the README.md file in each repository. This Quickstart will highlight the main steps, but please refer to that readme file.

  1. You will need to import a template repo into your own Github account. You can follow the Github instructions for importing a repo. The CyVerse template repos are:

  2. After importing the template, clone it to your local computer and develop the text of your tutorial. See the README.md file in your downloaded template for specific step-by-step instructions. CyVerse documentation is written in ReStructured Text, a plain text format very similar to Markdown. See the ReStructured Text examples on the next page.

  3. Once your materials are complete, please notify Tutorials@CyVerse.org that your tutorial is ready for inclusion in the main CyVerse documentation repo. We will review and verify the contribution, and add you as a maintainer repo in the CyVerse collection. If your documentation contains example data, we will also assist you in making sure that data is accessible to others who would use the documentation.

    Tutorial Creation Flowchart

    draft_new_lc_docs

Tip

You can use these templates and instructions to create your documentation without having it hosted on the CyVerse Learning Center. See the Read the Docs Docs.

Additional information, help

Post your question to the user forum: |Ask CyVerse|

Fix or improve this documentation

|Home_Icon|_ Learning Center Home