diff --git a/docs/index.md b/docs/index.md index 7ae00ba9ff..77a87de258 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,6 +6,7 @@ All hub configuration is in `hubs.yaml`. You can add a new hub by adding an entry there, and pushing that to github. ```{toctree} +structure configure operate custom-image diff --git a/docs/structure.md b/docs/structure.md new file mode 100644 index 0000000000..c7728eb9df --- /dev/null +++ b/docs/structure.md @@ -0,0 +1,102 @@ +# Documentation Structure + +We primarily offer documentation, peace of mind and expertise to +our users - and code/configuration is simply an implementation +detail. Well structured documentation aimed at different audiences is +essential to 2i2c's long term health. This document lists the audiencs +we serve, what kinda docs they might expect, and where we provide them. + +## Audiences + +For each feature we add or change we make, we should create & update +documentation for all of these audiences, as applicable. There are a +few key audiences that are outlined below. + +## The general public + +People visit our website to learn about us, and investigate if we could +be of use to them. Communicating what value we can add to them is +extremely important, so any feature we write should be integrated into +[our website](https://2i2c.org/). The focus should +be on the value we can add to potential users, and should link to +other kinda documentation for more detail if needed. + +## Hub users + +Ultimately, our hubs are built to serve researchers, students and instructors. +These are our *end users*, and they need to be able to +get their work done. + +The infrastructure we provide is primarily opinionated bundles of +upstream software, so we don't *need* to rewrite documentation for all +the software they might use. However, since we make opinionated choices +about JupyterHub deployments, some repetition of upstream documentation +that assumes the specific choices we already make is helpful. + +We should provide at least the following kinds of documentation: + +1. **Tutorials** for common workflows on our infrastructure, since this is + heavily driven by the opinionated choices we have made while building it. +2. **How-to guides** to help users accomplish a specific well defined task, + especially if it is something they know how to do in a different system. + The documentation titles should always be of the form **How do I ?** +3. **Component reference** to inform users where to find documentation for + the component they might be having issues with. Most users are unfamiliar + with the intricate details of what component does what, so might not be + able to find the appropriate place to look at. + +This documentation should exist in the [2i2c-org/pilot](https://github.com/2i2c-org/pilot) +repository, available at [2i2c.org/pilot](https://2i2c.org/pilot/) + +## Hub administrators + +Hub administrators are the interface between the 2i2c engineers running +the hub and the actual users of the hub. They are usually a part of the +community using the hub, and are interested in the *configuration* of +the hub infrastructure as well. They should be aware of possible +configuration options they can choose to serve their community best, and +be empowered to make those choices without interaction with 2i2c +engineers wherever possible. + +They help make decisions about the configuration of the hub that benefits +its users most, and hence we should provide at least the following kinds +of documentaiton. + +1. **Configuration guides** to help them *pick* the configuration that + will be best fit for each of our major features - such as + authentication, kind of user interface, etc. Their hubs are then + configured with these choices in collaboration with 2i2c staff. Each + guide should mention *how* this implementation can occur - possibly + with a link to documentation for 2i2c engineers . +2. **How-to guides** to help admins accomplish very specific tasks during + the course of hub usage. Their titles should always be of the form + **How do I <title>?**. + +This documentation should exist in the [2i2c-org/pilot](https://github.com/2i2c-org/pilot) +repository, available at [2i2c.org/pilot](https://2i2c.org/pilot/) + +## 2i2c engineers + +These are folks tasked with building, maintaining, debugging and fixing +2i2c infrastructure. Documentation targetting them should be in +[2i2c-org/pilot-hubs](https://github.com/2i2c-org/pilot-hubs). +repository (2i2c-org/pilot-hubs), regardless of the kind of hub it +relates to. Since we run our hubs openly, with best practices that can +be adopted by anyone, we should try write these to be as accessible to +non 2i2c staff as possible - no secret sauce, minimal 2i2c specific +process. + +Here are some contexts where they would need documentation. + +1. **Tutorials**, to help orient folks who might be working on areas + they aren't already familiar with. This should have clear links to + pre-requisite knowledge and how it can be acquired. +2. **How-to guides** for performing common tasks that have not been + automated yet. Their titles should always be of the form + **How do I <title>?** +3. **Topic guides** +3. **References**, describing in detail parts of our infrastructure and + its configuration. This should ideally be kept in the code describing + our infrastructure - for example, [terraform-docs](https://github.com/terraform-docs/terraform-docs) + for terraform code, JSON Schema based document generator for YAML, + etc. This helps them be in sync with what we are actually doing.