Documentation for end-users of 2i2c hubs

[choldgraf]

Problem statement

We currently have documentation for 2i2c Hub administrators at docs.2i2c.org, but we do not have a dedicated place for Hub users. This means that many users may not be familiar with how to do basic operations on a hub, or how to use it to its potential.

Solution

We need end-user documentation that covers the major aspects of doing work on a JupyterHub in the cloud. It should exist at a dedicated URL such as users.2i2c.org and should be easy to find for users that are unfamiliar with Jupyter workflows and may be unable to do things like log in to the JupyterHub.

We should define a basic Tutorial, as well as some common "How to"-style operations that we think 80% of hub users will want to do.

Appetite

1 sprint

Because a lot of this content is already out there, we should get a minimal viable product up within one sprint. This will help us get the most important pieces set up early on so that we have something to offer other communities.

Guidance

Including all of our current user personas in docs.2i2c.org is probably too much. Instead we should explore using three different documentation sites for these, and cross-linking between them. For example, something like:

User guide

users.2i2c.org

This is for end-users of a 2i2c Hub. AKA, somebody that logs on to a hub and wants to run their own workflows.

A good starting point is the Pangeo scientists guide and related user-facing documentation there, which is a good start for major workflows we should cover.

Administrator guide

administrators.2i2c.org

This is for somebody that administers a hub on behalf of others.

We can start with what we have at docs.2i2c.org, and spin that off into a dedicated guide. Probably some things in the Pangeo docs as well.

• Include information about how to add to / remove a package from a user image repo

About the service

service.2i2c.org

This is meta information about the service itself, it is designed for a decision maker who is considering using a 2i2c hub service.

User personas

I think there are three user personas to include:

• a classroom persona
• a team-based research persona
• a scalable+cloud computing persona

Out of scope

• This should not be a comprehensive guide to data science, it should be focused on the basic steps that 80% of our users would want to try within the first few weeks of them using a hub.
• This should not be a comprehensive "guide to Jupyter" - we want to assume some basic experience with the Jupyter ecosystem, and point to other tutorials and guides for people that need to learn from scratch, and focus these docs on the workflows that are particularly useful for our personas

Related issues

• Provide Pangeo users with documentation that is not maintained by the Pangeo community infrastructure#781

[sgibson91]

I would also add that a "comprehensive guide to JupyterHub" is also out of scope - we should upstream/link out other resources/advanced usage patterns, etc.