Add startup times documentation

community-lead/billing/responsiveness.md

@@ -1,3 +1,4 @@
+(community-lead:billing:responsiveness)=
 # How to balance cloud responsiveness and cost
 
 There is a tradeoff between how responsive a hub is and its cost. This is primarily determined by the **size of the nodes** that are used for user sessions.
@@ -34,4 +35,8 @@ Many 2i2c hubs use a **balanced approach**:
 - Have the ability to provision smaller nodes for quick scaling during peak times
 - Allow specific high-memory users to request larger dedicated nodes
 
-This provides reasonable responsiveness while keeping costs manageable. The 2i2c engineering team works with communities to find the right balance for their usage patterns.
+This provides reasonable responsiveness while keeping costs manageable. The 2i2c engineering team works with communities to find the right balance for their usage patterns.
+
+```{seealso}
+Users may wonder why their server takes time to start. See [](user:faq:startup-time) for a user-friendly explanation of typical startup times.
+```

user/basics/index.md

@@ -0,0 +1,8 @@
+# Hub basics
+
+This section covers fundamental information about using your 2i2c JupyterHub.
+
+```{toctree}
+:maxdepth: 1
+startup
+```

user/basics/startup.md

@@ -0,0 +1,35 @@
+(user:faq:startup-time)=
+# What is a typical hub start-up time?
+
+User server startup time ranges from **a few seconds** to **10 minutes**, depending on two main factors:
+
+## Factor 1: Resources available on a node
+
+When a server starts, it requests resources from a node.
+
+**If a node already exists with sufficient resources:**
+- Server creation takes only a few seconds
+
+**If a suitable node doesn't exist or lacks resources:**
+- The autoscaler creates a new node, which takes 2 to 10+ minutes
+- Node creation time depends on the cloud provider and machine type (larger machines like GPUs often take longer)
+- If startup exceeds 10 minutes, you'll see a `TimeoutError` and need to restart your server to use the newly created node
+- This timeout is uncommon but can occur with certain machine types
+
+
+## Factor 2: Environment image availability
+
+When a user server starts, JupyterHub then finds and loads the **environment image**, which contains all the tools available to the user.
+
+**If the image is already on the node:**
+- Server startup is much faster since no download is needed
+
+**If the environment image isn't on the node:**
+- The image must be pulled from the container registry
+- This takes a few minutes depending on image size and network conditions
+- Image pulling always happens if a new node was just created
+
+
+```{important}
+Startup time can be reduced through strategies like maintaining minimum node counts or pre-pulling images, but these increase costs. Learn more about balancing responsiveness and cost in [](community-lead:billing:responsiveness).
+```

user/environment/choose.md

@@ -51,6 +51,10 @@ We recommend always explicitly specifying a version number in the `TAG` field ra
 jovyan@user:~$ echo $JUPYTER_IMAGE
 ```
 
+```{note}
+If the image isn't already cached on a node, it will need to be pulled from the container registry, which can add several minutes to startup time. Learn more about startup times in [](user:faq:startup-time).
+```
+
 ### The "Dynamic Image Building" option
 
 This allows users to dynamically build an environment image for their Jupyter server, similar to [mybinder.org](https://mybinder.org).

user/get-started.md

@@ -19,6 +19,10 @@ For other hubs, you will presented with a *Server Options* page where you can se
 
 ![JupyterHub server options](/images/server-options.jpeg)
 
+```{seealso}
+Learn more about typical server startup times in [](user:faq:startup-time).
+```
+
 It is important to use cloud resources responsibly to maximize efficiency and minimize carbon emissions. Selecting a larger server incurs a larger financial cost, as well as an environmental cost!
 
 Best practices for using resources responsibly include

user/index.md

@@ -56,6 +56,14 @@ Distribute notebooks and files
 Contact 2i2c Support for assistance
 :::
 
+:::{grid-item-card} Frequently Asked Questions
+:text-align: center
+:link: basics/startup
+:link-type: doc
+
+Common questions about using your hub
+:::
+
 ::::
 
 ## All User Topics
@@ -64,6 +72,7 @@ Contact 2i2c Support for assistance
 :maxdepth: 2
 
 get-started
+basics/index
 data/index
 environment/index
 sharing/index