From 659605fb907d6cb8a18e5c776204bbab96ba9d5b Mon Sep 17 00:00:00 2001
From: kafonek <kafonek@gmail.com>
Date: Tue, 4 Jun 2019 05:51:29 -0400
Subject: [PATCH] Adding directions for configuring a 'shared-directory'

---
 docs/howto/content/share-data.rst       | 13 +++++-
 docs/howto/content/shared-directory.rst | 56 +++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 1 deletion(-)
 create mode 100644 docs/howto/content/shared-directory.rst

diff --git a/docs/howto/content/share-data.rst b/docs/howto/content/share-data.rst
index b0e7e06..0a83edc 100644
--- a/docs/howto/content/share-data.rst
+++ b/docs/howto/content/share-data.rst
@@ -5,7 +5,7 @@ Share data with your users
 ==========================
 
 There are a few options for sharing data with your users, this page covers
-a few useful patterns.
+a few useful patterns.  
 
 Option 1: Distributing data with `nbgitpuller`
 ==============================================
@@ -78,3 +78,14 @@ From now on, when a new user account is created, their home directory will
 have this symbolic link (and any other files in ``/etc/skel``) in their home
 directory. This will have **no effect on the directories of existing
 users**.
+
+Option 3: Create a directory for users to share Notebooks and other files
+=========================================================================
+
+You may want a place for users to share files with each other rather than 
+only having administrators share files with users (Option 2).  In this 
+configuration, any user can put files into ``/srv/scratch`` that other users
+can read.  However, only the user that created the file can edit the file.
+
+For information on creating and sharing a **shared directory** for users, see
+:ref:`howto/content/shared-directory`.
\ No newline at end of file
diff --git a/docs/howto/content/shared-directory.rst b/docs/howto/content/shared-directory.rst
new file mode 100644
index 0000000..7290204
--- /dev/null
+++ b/docs/howto/content/shared-directory.rst
@@ -0,0 +1,56 @@
+.. _howto/content/share-data:
+
+=================================================
+Shared-directory for users to "publish" Notebooks
+=================================================
+
+One way for users to share or "publish" Notebooks in a JupyterHub environment
+is to create a shared directory.  Any user can create files in the directory, 
+but only the creator may edit that file afterwards.
+
+For instance, in a Hub with three users, User A develops a Notebook in their
+`/home` directory.  When it is ready to share, User A copies it to the 
+`shared` directory.  At that time, User B and User C can see User A's
+Notebook and run it themselves (or view it in a Dashboard layout 
+such as `voila` or `panel` if that is running in the Hub), but User B
+and User C cannot edit the Notebook.  Only User A can make changes.
+
+
+#. **Log** in to your JupyterHub as an **administrator user**.
+
+#. **Create a terminal session** with your JupyterHub interface.
+
+   .. image:: ../../images/notebook/new-terminal-button.png
+      :alt: New terminal button.
+      
+#. **Create a folder** where your data will live. We recommend placing shared
+   data in ``/srv``.  The following command creates a directory ``/srv/scratch``
+
+   .. code-block:: bash
+
+      sudo mkdir -p /srv/scratch
+      
+#. **Change group ownership** of the new folder
+
+  .. code-block:: bash
+      
+      sudo chown  root:jupyterhub-users /srv/scratch
+      
+#. **Change default permissions to use group**.  The default permissions for new 
+   sub-directories uses the global umask (``drwxr-sr-x``), the ``chmod g+s`` tells
+   new files to use the default permissions for the group ``jupyterhub-users`` 
+   (``rw-r--r--``)
+   
+   .. code-block:: bash
+   
+      sudo chmod 777 /srv/scratch
+      sudo chmod g+s /srv/scratch
+   
+   
+#. **Create a symbolic link** to the scratch folder in users home directories
+
+   .. code-block:: bash
+
+      sudo ln -s /srv/scratch /etc/skel/scratch
+   
+