Note on the AllFredHutch team. We want everyone included, but GitHub can be chatty. Go here to see how to set your personal settings to NOT automatically watch every team you are part of.

Contributing to this wiki

This curated Wiki relies upon the Fred Hutch research community itself to improve, expand and evolve over time. Because the wiki's content spans many research areas, we need and welcome contributions from a similarly wide range of researchers and Fred Hutch staff whether as novice reviewers for a topic outside of their expertise or as expert contributors for those topics of most interest to them. No contribution is too little (or too large).

Details

Contributing Directly via GitHub

Contributing via an external editor

Wiki content style guide

Repository structure

Building a copy of this wiki locally

For Admins

Contributing directly via GitHub

We manage the content of this site via a set of markdown files that contain long article-style text with an emphasis on the use of outline structures to allow related content to show up near each other but with the ability to use the automatically rendered Table of Contents to jump around the documents.

To edit one of the content-containing markdowns (see below regarding Repo structure for more info about where these markdowns are) from GitHub, follow these steps:

1. Create a branch off the master branch for your edits (do not fork the repo or create branches from other branches). Consider naming the branch in such a way that indicates what domain the edits will primarily be in (such as "generation-typos" or "intro-to-rhino"). Avoid making branches with uninformative names whenever possible. For your content to be merged into the master, it will need to be edited by others, and it is possible that others may have substantial content to add to your edits. If the branches are named according to content being added (generally) then others can contribute to that content too.
2. Commit your edits to existing markdowns as you go, and update from the master branch before continuing to work on your branch. You will reduce future conflicts if you get in the habit of updating from the master and committing frequently.
3. Publish/push your branch to GitHub to save your work and let us know you're working on something.
4. When you are done editing, create a pull request from your branch. Suggest reviewers based on the content of the edits. Request admin assistance if your content may be new and need to be hooked up to the sidebar or other web-specific needs (this is currently done by tagging vortexing or bmcgough for a review).
   >Note: If you are editing existing content and the page has a listing for the Primary Reviewers like this: primary_reviewers: somegithubusername then when you submit the pull request please request a review from those usernames.
5. Reviewers will sign off on edits by approving or providing comments on a pull request, ideally one "expert" and one "novice" based on field of expertise. If there is a primary_reviewer listed for content then one of the reviews must be from one of those members. Others may move your content to combine it with other work, or make edits that you may want to review as well. Keep an eye on your pull requests and comments on it in order to check back in if someone's edits need your review as well.
6. Once reviews have been obtained, the pull request can be merged into the master and then any edits go live to the site here.

Afterwards: Please remember to make a markdown for yourself in our _contributors directory so that we can give you credit for your contributions publicly on the site.

Contributing via an external text editor

You can also contribute to the wiki from external editors that can interoperate with GitHub. We have had good experience with Atom but other text editors have GitHub integration as well. Also there is a tutorial on how to use VSCode which is what you will want to use if you plan to contribute many screenshots or other images.

Wiki Content Style Guide

Github-Flavored Markdown

The content of this site is generated using GitHub "flavored" markdown. A cheat sheet for the code required to create things like headings and table is here. Our page TOC's are generated from these headings, so use ## H2 as your first level, and headings H2, H3 and H4 show up automatically in our TOC's).

Content Structure

Our goal is the generate article-style content (with the exception of the demo's/resource library pages), with the following general sections:

Introduction

An introductory paragraph summarizing the page must be included and should be comprehensible for novices and experts alike. This paragraph is a good place to define domain-specific words that appear in your article. Also include a description or set of examples that might highlight why the reader might want to keep reading, whether they are novice or expert. Good introductions can use your own research project to give the reader some context.

Graduated Content

The main content of the pages is up to you to structure. Keep in mind that the wiki's articles are meant to provide enough background for a variety of readers to know what sorts of questions related to their particular research to pose when looking for in-person help. Create headings that an advanced user could use the TOC links to go directly to the content they want while novices can also browse and slowly increase the complexity of the material throughout the page. This gradual increase in content complexity from basic to advanced will give a reader some basic understanding of the topic before heading directly to the particular web-based (Fred Hutch sponsored or otherwise), in-person training/office hours, or on-campus expert to discuss or learn about their project in more detail.

Available Resources

Since we are not intending to write comprehensive explanations, the Available Resources sections in our Wiki are really the intended endpoint for our readers. This section should focus on linking to comprehensive and established external educational resources of interest to the topic, online training tools from established entities, additional more detailed Fred Hutch documentation provided by Fred Hutch based experts/providers, in-person training opportunities at the Fred Hutch or locally, and if possible and approved by the expert, specific highlights of on-campus experts in a given field who are willing and able to provide consulting or advice on the topic. Please make sure all links to any other site are correct and tested!!!!

If a content section is relatively short and cohesive, there should be one Available Resources section at the bottom of the page. However, as content sections grow and perhaps themes evolve, consider having a specific Available Resources section after the end of a unified topic section for which the resources mentioned are thematically related.

Inserting Links

If you would like to insert a link to another page in our site, please use:

[text you want to have highlighted](/page_name/)

If it is a link to an external site use:

[text you want to have highlighted](https://my.url.com)

In-text Images

If you'd like to add images to your entry, some text editors (eg. Atom or VSCode via their respective plugins) allow for copy-and-pasting of images. You can read some instructions on how to get set up with VSCode in one of the Computing Demo's.

One edit is that in order for Jekyll to correctly render the images in a page, the following text is the example format that that call to the image needs to be in for a markdown in the _compdemos folder:

![]({{ site.baseurl }}/compdemos/assets/2018-06-13-16-47-59.png)

If the markdown you are editing is in one of the other folders you'll need to change the compdemos string to whatever the text of your folder is.

Both Atom and VSCode will make a directory called assets in the directory where the markdown is, and then will copy your in-text image file there so you can commit it all to the repo.

External Videos and Images

Youtube

When linking to videos like screencasts you typically want to show an image screenshot and clicking on that screenshot starts the video. Images of videos are stored at https://img.youtube.com/vi and they use the same video id you find in Youtube URLs, so The Gift of Time is https://youtu.be/rN7cmb1K2yA. To embed, insert this into markdown:

[![The Gift of Time](https://img.youtube.com/vi/rN7cmb1K2yA/0.jpg)](https://youtu.be/rN7cmb1K2yA "Click to see The Gift of Time")

It is also important to consider the following parameters for videos from outside sources:

• rel=0 - this restricts the related videos shown at the end of payback to videos from the same channel rather than account-based recommendations
• iv_load-policy - set to 1 to display video annotations by default and 3 to disable annotations

So the above link modified would be:

[![The Gift of Time](https://img.youtube.com/vi/rN7cmb1K2yA/0.jpg)](https://youtu.be/rN7cmb1K2yA?rel=0&iv_load_policy=3 "Click to see the amazing kitten")

If you need to make screencasts, free software exist for Windows, Linux, and OSX.

Referencing a Fred Hutch username

Please if you need to reference a Fred Hutch username, do not write the entire email address out, just put the username in backticks like this:

`username`

Repo structure

Folders and Files that may be Edited:

Draft Folders with Templates for New Content

NOTE: All draft content should be stored in the draft folder until it is ready for publication, and then an admin will move it to where it needs to go if it is new content, OR the writer can move demo's themselves when they are ready to go live.

For new content: https://github.com/FredHutch/wiki/blob/master/draft/contentTemplate.md

For new contributor entries: https://github.com/FredHutch/wiki/blob/master/draft/contributorTemplate.md

Folders with Existing Content

Data Generation Content, organized with filenames that start with xxx_ based on what section they are intended to show up in the sidebar: https://github.com/FredHutch/wiki/tree/master/_generation

Data Generation Resource Library (note all markdowns in this folder will be rendered): https://github.com/FredHutch/wiki/tree/master/_gendemos

Bioinformatics Content, organized with filenames that start with xxx_ based on what section they are intended to show up in the sidebar: https://github.com/FredHutch/wiki/tree/master/_bioinformatics

Bioinformatics Resource Library (note all markdowns in this folder will be rendered): https://github.com/FredHutch/wiki/tree/master/_infdemos

Computing Content, organized with filenames that start with xxx_ based on what section they are intended to show up in the sidebar: https://github.com/FredHutch/wiki/tree/master/_computing

Computing Resource Library (note all markdowns in this folder will be rendered): https://github.com/FredHutch/wiki/tree/master/_compdemos

Contributors List (note all markdowns in this folder will be rendered): https://github.com/FredHutch/wiki/tree/master/_contributors

Building the site locally

You may want to build a copy of this wiki locally (on your own computer) to make sure that it looks the way you want before pushing your changes.

Steps

1. clone the repo somwhere

2. Install Ruby (version 1.9.2 or later). Note: most modern Mac computers already have Ruby installed. If you still need Ruby, it can be found here.

3. On Mac, install xcode commandline tools xcode-select --install

4. You may need to install bundler. Type which bundler to see if it is already installed. If nothing is returned, then install bundler with gem install bundler. If that fails, try sudo gem install bundler.

5. To build and view the site locally, from the cloned repo directory run bundle install then run bundle exec jekyll serve. Once the site is built you can view it at http://localhost:4000.

Checking for broken links

To check for broken links, you can type rake test. This will exit with an error if there are any broken links, and list the broken links and the files they are found in.

If you are inside the Fred Hutch network, you can type rake testlocal and that will include internal URLs in the check (these are normally excluded because CircleCI does not have access to them).

You can also look at the most recent CircleCI build to see the list of broken links.

For Admins:

Pages that run Demo and Contributors Collection pages:

Computing: https://github.com/FredHutch/wiki/blob/master/computingdemos.md

Bioinformatics: https://github.com/FredHutch/wiki/blob/master/informaticsdemos.md

Contributors list: https://github.com/FredHutch/wiki/blob/master/contributorslist.md

Folders containing website configuration files

Main website configuration file: https://github.com/FredHutch/wiki/blob/master/_config.yml

Navigation yml: https://github.com/FredHutch/wiki/tree/master/_data

Custom styling that overrides the remote theme: https://github.com/FredHutch/wiki/tree/master/assets/css

Header and footer configs: https://github.com/FredHutch/wiki/tree/master/_includes