Skip to content

Commit

Permalink
Updated draft FAQ page.
Browse files Browse the repository at this point in the history 
A suggested structure for the FAQ page.  Text is rough, there are no images, and lots of links need to be added, but this is what I'm thinking.
  • Loading branch information
@tnabtaf @bebatut
tnabtaf authored and bebatut committed Jun 7, 2018
1 parent 20067f6 commit 294c2e8
Showing 1 changed file with 132 additions and 39 deletions.
171 changes: 132 additions & 39 deletions faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,64 +5,150 @@ layout: faq
1. TOC
{:toc}

# What is this website?
# Overview Questions

This website is a collection of tutorials developed and maintained by the worldwide Galaxy community. You can learn more about this effort with reading our [article](https://www.biorxiv.org/content/early/2018/04/05/225680).
## What is this website?

# How can I get some help?
This website is a collection of tutorials developed and maintained by the [worldwide Galaxy community](https://galaxyproject.org/). You can learn more about this effort by reading our [article](https://www.biorxiv.org/content/early/2018/04/05/225680).

If you have any questions, you can reach us using the [Gitter chat](https://gitter.im/Galaxy-Training-Network/Lobby?utm_source=share-link&utm_medium=link&utm_campaign=share-link).
## What is Galaxy?

# How can I use these ressources to learn about Galaxy and data analyses?
[Galaxy](https://galaxyproject.org/) is an open data integration and analysis platform for the life sciences, and it is particularly well-suited for data analysis training in life science research.

- Parse the website to find interesting tutorials
- Find a Galaxy instance to use for the tutorial
- Take one of our interactive tour directly on a Galaxy instance
## What are the tutorials for?

# How can I use these ressources as an instructor?
These tutorials can be used for learning and teaching how to use Galaxy for general data analysis, and for specific domains from assembly to differential gene expression analysis with RNA-Seq data.

## What audiences are the tutorials for?

There are two distinct audiences for these materials.

1. **Self-paced individual learners.** These tutorials provide everything you need to learn a topic, from explanations of basic concepts to detailed hands-on exercises.
2. **Instructors.** They are also designed to be used by instructors in teaching/training settings. Slides, and detailed tutorials are provided. Some tutorials also include computational support such as Docker images that can be used to scale the lessons up to many participants.

## How is the content licensed?

The content of this website is Creative Commons Attribution 4.0 ([License]({{ site.github_repository }}/LICENSE.md)).

## How can I cite this effort?

We wrote an [article](https://www.biorxiv.org/content/early/2018/04/05/225680) about our effort there. You can cite it and then giving us some credit.


# For Individual Learners

Learning Galaxy and data analysis on your own, at your own pace? This material is for you.

## Where do I start?

If you are new to Galaxy then start with one of the introductory topics. These introduce you to concepts that are useful in Galaxy, no matter what domain you are doing analysis in.

If you are already familiar with Galaxy basics and want to learn how to use it in a particular domain (for example, ChIP-Seq), then start with one of those topics.

## How do I use this material?

Many topics include slide decks and if the topic you are interested in has slides then start there. These will introduce the topic and important concepts.

Most of your learning will happen in the next step - the hands-on tutorials. This is where you'll become familiar with using the Galaxy interface and experiment with different ways to use Galaxy and the tools in Galaxy.

## Where can I run the hands-on tutorials?

To run the hands-on tutorials you need a Galaxy server to run them on.

Some topics have a Docker image that can be installed and run on all participants' laptops. These images contain Galaxy instances that include all tools and datasets used in a tutorial, as well as saved analyses and repeatable workflows that are relevant.

You can also run many tutorials on public Galaxy servers. These servers are available to anyone on the world wide web and have all the tools that are needed by a specific tutorial.

If your organization (or consortia) has its own Galaxy server, then you may be able to run tutorials on that. Before you start you should confirm that all needed tools and reference genomes are available on your server.

Finally, you can also run your tutorials on cloud-based infrastructures. Galaxy is available on many national research infrastructures such as Jetstream (United States), GenAP (Canada), GVL (Australia), CLIMB (United Kingdom), and more. These instances are typically easy to launch before you start, and easy to shut down when you are done.

If you are already familiar with, and have an account on Amazon Web Services then you can also launch a Galaxy server there.

## How can I get help?

**HELP FOR INDIVIDUAL LEARNERS**

If you have questions about this training material, you can reach us using the [Gitter chat](https://gitter.im/Galaxy-Training-Network/Lobby). You'll need a [GitHub](https://github.com/) or [Twitter](https://twitter.com/) account to post questions. If you have questions about Galaxy outside the context of training, see the [Galaxy Support page](https://galaxyproject.org/support/).

# For Instructors

This material can also be used to teach Galaxy and data analysis in a group setting to students and researchers.

## Where do I start?

Spend some time exploring the different tutorials and the different resources that are available. Become familiar with the structure of the tutorials and think about how you might use them in your teaching.

## What Galaxy instance should I use for my training?

To teach the hands-on tutorials you need a Galaxy server to run the examples on

Some training topics have a Docker image that can be installed and run on all participants' laptops. These images contain Galaxy instances that include all tools and datasets used in a tutorial, as well as saved analyses and repeatable workflows that are relevant.

You can also run many tutorials on several public Galaxy servers. These servers are available to anyone on the world wide web and will also have all the tools that are needed by a specific tutorial. If you choose this option then you should work with that server's admins to confirm that think the server can handle the workload for a workshop.

If your organization (or consortia) has its own Galaxy server, then you may be able to run tutorials on that. This can be ideal because then the instance you are teaching on is the same you your participants will be using after the training. They'll also be able to revisit any analysis they did during the training. If you pursue this option you'll need to work with your organization's Galaxy Admins to confirm that

- the server can support a room full of people all doing the same analysis at the same time.
- all tools and reference datasets needed in the tutorial are locally installed. Some tutorials include scripts that install all needed tools and data on an existing server.
- all participants will be able to create/use accounts on the system.

TODO: Training Infrastructure as a Service on useGalaxy.eu

Finally, you can also run your training on cloud-based infrastructures. Galaxy has been available on Amazon Web Services for years, and is also available on many national research infrastructures such as Jetstream (United States), GenAP (Canada), GVL (Australia), CLIMB (United Kingdom), and so on.

## What are the best practices for teaching with Galaxy?

- Parse the website to find interesting tutorials to teach
- Find a Galaxy instance to use for the workshop
- Check the annotated Galaxy instance
- Training Infrastructure as a Service on useGalaxy.eu
- Docker image
- Deployment of the tools, data, etc on an exisiting instance using our provided scripts
- Have a look at our [Good practices slides]()

# How can I make sure a tutorial is running on a Galaxy instance?

- Badge?
- Installations
## How do I get help?

The support channel for instructors is the same as for individual learners. We suggest you start by posting a question to the Galaxy Training Network Gitter channel. Anyone can view the discussion, but you'll need to login (using your GitHub or Twitter account) to add to the discussion.

If you have questions about Galaxy in general (that are not training-centric) then there are numerous support options.

# Contributing

First off, thanks for your interest in contributing to the Galaxy training materials!

Individual learners and instructors can make these training more effective by contributing back to them. You can report mistakes and errors, create more content, etc. Whatever is your background, there is a way to contribute. See the [contributing page]() for how.

# How can I contribute?
TODO: @tnabtaf suggests moving rest of this section to CONTRIBUTING.md

First off, thanks for taking the time to contribute!
: via the GitHub website, via command-line or even without dealing with GitHub.

You can report mistakes or errors, create more contents, etc. Whatever is your background, there is probably a way to do it: via the GitHub website, via command-line or even without dealing with GitHub.

You can check our [tutorials](http://galaxyproject.github.io/training-material/topics/contributing) for more details.

We will address your issues and/or assess your change proposal as promptly as we can, and help you become a member of our community.

## How can I give feedback?

- tutorial level
- contributions
- issues


## How can I report mistakes or errors?

The easiest way to start contributing is to [file an issue]({{ site.github_repository }}/issues/new) to tell us about a spelling mistake or a factual error. You can then introduce yourself and meet some of our community members.
The easiest way to start contributing is to [file an issue]({{ site.github_repository }}/issues/new) to tell us about a problem such as a typo, spelling mistake, or a factual error. You can then introduce yourself and meet some of our community members.

## How can I fix mistakes or expand an existing tutorial using the GitHub interface?

Check our tutorial to learn how to use the GitHub interface

## How can I create new content without dealing with git?

If you feel uncomfortable with using the git and the [GitHub flow](https://guides.github.com/introduction/flow/), you can write a new tutorial with any text editor. and contact us: we will work together to integrate it.
If you feel uncomfortable with using the git and the [GitHub flow](https://guides.github.com/introduction/flow/), you can write a new tutorial with any text editor and then contact us. We will work together to integrate the new content.

## How can I contribute in "advanced" mode?

Most of the content is written in Markdown with some metadata (or variables) stored in YAML. To learn how to add new content, check out our [series of tutorials to create new content]({{ site.baseurl }}/topics/contributing/):
Most of the content is written in [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/) with some metadata (or variables) stored in [YAML](http://yaml.org/). To learn how to add new content, check out our [series of tutorials on creating new content]({{ site.baseurl }}/topics/contributing/):

- [Writing content in markdown to create a new tutorial]({{ site.baseurl }}/topics/contributing/tutorials/create-new-tutorial-content/tutorial.html)
- [Defining metadata for a new tutorial]({{ site.baseurl }}/topics/contributing/tutorials/create-new-tutorial-metadata/tutorial.html)
- [Setting up the infrastructure]({{ site.baseurl }}/topics/contributing/tutorials/create-new-tutorial-jekyll/tutorial.html) to run Jekyll and check the website generation
- [Setting up the infrastructure]({{ site.baseurl }}/topics/contributing/tutorials/create-new-tutorial-jekyll/tutorial.html) to run [Jekyll](https://jekyllrb.com/) and check the website generation
- [Creating Interactive Galaxy Tours]({{ site.baseurl }}/topics/contributing/tutorials/create-new-tutorial-tours/tutorial.html)
- [Building a Docker flavor for a tutorial]({{ site.baseurl }}/topics/contributing/tutorials/create-new-tutorial-docker/tutorial.html)
- [Including a new topic]({{ site.baseurl }}/topics/contributing/tutorials/create-new-topic/tutorial.html)
Expand All @@ -81,18 +167,31 @@ Pull requests will be merged by the training team members after at least one oth

## What can I do to help the project?

In [issues](https://github.com/galaxyproject/training-material/issues), you will find lists of issues to fix and features to change (with the "newcomer-friendly" label for example). Feel free to solve them.
In [issues](https://github.com/galaxyproject/training-material/issues), you will find lists of issues to fix and features to implement (with the "newcomer-friendly" label for example). Feel free to solve them.

We strongly recommend you read and follow [Software Carpentry's](https://software-carpentry.org/) recommendations on [lesson design](https://swcarpentry.github.io/lesson-example/01-design/) and [lesson writing](https://swcarpentry.github.io/instructor-training/19-lessons/) if you plan to add or change some training materials, and also to check the [structure of the training material](#how-the-training-material-is-structured).

# Other Questions

We strongly recommend you read and follow Software Carpentry's recommendations on [lesson design](https://swcarpentry.github.io/lesson-example/01-design/) and [lesson writing](https://swcarpentry.github.io/instructor-training/19-lessons/) if you plan to add or change some training materials, and also to check the [structure of the training material](#how-the-training-material-is-structured).
## Are there any upcoming events focused on Galaxy Training?

## Is there any interesting events in which I could participate?
Yes. As of May 2018, these events are on the horizon:

Contribution Fest
- GCC
- Every 3 months on the 3rd Friday: check our next event
* [CarpentryCon 2018](http://www.carpentrycon.org/), 30 May - 1 June, Dublin, Ireland
* Not specifically about Galaxy Training, but an excellent opportunity to gather with other computational science educators. [Bérénice Batut](@bebatut) will present a poster and lightning talk on [Community-Driven Training for Biological Data Analysis with the Galaxy Training Network](https://github.com/carpentries/carpentrycon/blob/master/Sessions/2018-05-30/13-Poster-Session/abstract-berenice-batut.md)
* [GCCBOSC 2018](https://gccbosc2018.sched.com/), June 25-30, Portland, Oregon, United States
* The annual gathering of the Galaxy Community is an opportunity to learn from experienced Galaxy trainers and to contribute to these efforts:
* [Bioinformatics Training and Education with the Galaxy Training Network](http://sched.co/Drp9), training session on how to use and contribute to these materials, presented by [Bérénice Batut](@bebatut)
* [A fruitful year for the Galaxy Training materials], conference talk by [Bérénice Batut](@bebatut)
* The *Galaxy documentation, analysis, and training (Galaxy DAT)* track of [CollaborationFest](https://galaxyproject.org/events/gccbosc2018/collaboration/), June 29 - July 2. Focus on expanding Galaxy community resources like training materials and documentation.
* Quarterly online training material Contribution Fests: The training community will meet online on the 3rd Friday of every 3rd month to focus on enhancing particular areas of the training material.

Is the above list now out of data (it happens). See the [Galaxy Community Events Calendar](https://galaxyproject.org/events/) for what coming up right now.

# How is the training material structured?

TODO: Suggest moving this to contributing.

Each training material is related to a topic. All training materials (slides, tutorials, ...) related to a topic are found in a dedicated directory (*e.g.* `transcriptomics` directory contains the material related to transcriptomis analysis). Each topic have the following structure:

```
Expand All @@ -117,16 +216,10 @@ Each training material is related to a topic. All training materials (slides, tu

You want to add a new topic? You can check our [dedicated tutorial]({{ site.baseurl }}/topics/contributing/tutorials/create-new-topic/tutorial.html) and also contact us to discuss about it.

# How can I give feedbacks?

- tutorial level
- contributions
- issues

# How is the content licensed?
# What's not yet listed above.

The content of this website is Creative Commons Attribution 4.0 ([License]({{ site.github_repository }}/LICENSE.md)).
- Interactive tours (where to cover these?)

# How can I cite this effort?

We wrote an [article](https://www.biorxiv.org/content/early/2018/04/05/225680) about our effort there. You can cite it and then giving us some credit.

0 comments on commit 294c2e8

Please sign in to comment.