Creating Documentation in the CyVerse Learning Center¶
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.
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
We will use the following platform(s):
|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 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
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).
On the GitHub site, click the “Issues” tab near the top of the screen.
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.
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.
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:
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.
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.
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.