[ZEPPELIN-2036] add documentation on separating workspaces (public/pr…

…ivate)

### What is this PR for?
This is to add more description in documentation about notebook workspaces. Also some details from user mailing list [here](https://lists.apache.org/thread.html/d94276521942c90cca1325514ea93b737a517679dd0f6f7eb287492a%3Cusers.zeppelin.apache.org%3E)

### What type of PR is it?
Improvement | Documentation

### Todos
* [x] - add desc

### What is the Jira issue?
[ZEPPELIN-2036](https://issues.apache.org/jira/browse/ZEPPELIN-2036)

### How should this be tested?
green CI/ if description clear

### Screenshots (if appropriate)

### Questions:
* Does the licenses files need update? no
* Is there breaking changes for older versions? no
* Does this needs documentation? no

Author: Khalid Huseynov <[email protected]>

Closes apache#1965 from khalidhuseynov/docs/private-workspace and squashes the following commits:

fae6410 [Khalid Huseynov] fix formating: add lines
c85ee6e [Khalid Huseynov] rewording
cec8bbd [Khalid Huseynov] add public vs. private
8703770 [Khalid Huseynov] add description on separating workspaces

docs/security/notebook_authorization.md

@@ -24,14 +24,14 @@ limitations under the License.
 <div id="toc"></div>
 
 ## Overview
-We assume that there is an **Shiro Authentication** component that associates a user string and a set of group strings with every NotebookSocket. 
+We assume that there is an **Shiro Authentication** component that associates a user string and a set of group strings with every NotebookSocket.
 If you don't set the authentication components yet, please check [Shiro authentication for Apache Zeppelin](./shiroauthentication.html) first.
 
 ## Authorization Setting
-You can set Zeppelin notebook permissions in each notebooks. Of course only **notebook owners** can change this configuration. 
+You can set Zeppelin notebook permissions in each notebooks. Of course only **notebook owners** can change this configuration.
 Just click **Lock icon** and open the permission setting page in your notebook.
 
-As you can see, each Zeppelin notebooks has 3 entities : 
+As you can see, each Zeppelin notebooks has 3 entities :
 
 * Owners ( users or groups )
 * Readers ( users or groups )
@@ -42,18 +42,35 @@ As you can see, each Zeppelin notebooks has 3 entities :
 Fill out the each forms with comma seperated **users** and **groups** configured in `conf/shiro.ini` file.
 If the form is empty (*), it means that any users can perform that operation.
 
-If someone who doesn't have **read** permission is trying to access the notebook or someone who doesn't have **write** permission is trying to edit the notebook, Zeppelin will ask to login or block the user. 
+If someone who doesn't have **read** permission is trying to access the notebook or someone who doesn't have **write** permission is trying to edit the notebook, Zeppelin will ask to login or block the user.
 
 <center><img src="../assets/themes/zeppelin/img/docs-img/insufficient_privileges.png"></center>
 
-By default when you create a new note, the owner is the user who create it. And the readers/writers is empty which means it is shared publicly. But if you don't want it to be shared by default. You can set `zeppelin.notebook.public` to be false in `zeppelin-site.xml`.
+## Separate notebook workspaces (public vs. private)
+By default, the authorization rights allow other users to see the newly created note, meaning the workspace is `public`. This behavior is controllable and can be set through either `ZEPPELIN_NOTEBOOK_PUBLIC` variable in `conf/zeppelin-env.sh`, or through `zeppelin.notebook.public` property in `conf/zeppelin-site.xml`. Thus, in order to make newly created note appear only in your `private` workspace by default, you can set either `ZEPPELIN_NOTEBOOK_PUBLIC` to `false` in your `conf/zeppelin-env.sh` as follows:
+
+```
+export ZEPPELIN_NOTEBOOK_PUBLIC="false"
+```
+
+or set `zeppelin.notebook.public` property to `false` in `conf/zeppelin-site.xml` as follows:
+
+```
+<property>
+  <name>zeppelin.notebook.public</name>
+  <value>false</value>
+  <description>Make notebook public by default when created, private otherwise</description>
+</property>
+```
+
+Behind the scenes, when you create a new note only the `owners` field is filled with current user, leaving `readers` and `writers` fields empty. All the notes with at least one empty authorization field are considered to be in `public` workspace. Thus when setting `zeppelin.notebook.public` (or corresponding `ZEPPELIN_NOTEBOOK_PUBLIC`) to false, newly created notes have `readers` and `writers` fields filled with current user, making note appear as in `private` workspace.
 
 ## How it works
 In this section, we will explain the detail about how the notebook authorization works in backend side.
 
 ### NotebookServer
 The [NotebookServer](https://github.com/apache/zeppelin/blob/master/zeppelin-server/src/main/java/org/apache/zeppelin/socket/NotebookServer.java) classifies every notebook operations into three categories: **Read**, **Write**, **Manage**.
-Before executing a notebook operation, it checks if the user and the groups associated with the `NotebookSocket` have permissions. 
+Before executing a notebook operation, it checks if the user and the groups associated with the `NotebookSocket` have permissions.
 For example, before executing a **Read** operation, it checks if the user and the groups have at least one entity that belongs to the **Reader** entities.
 
 ### Notebook REST API call