add docs for collections [ci skip]

docs/administration-guide/05-setting-permissions.md

@@ -77,4 +77,4 @@ Pulses act a bit differently with regard to permissions. When a user creates a n
 ---
 
 ## Next: custom segments and metrics
-Learn how to define custom segments and commonly referenced metrics in the [next section](06-segments-and-metrics.md).
+Learn how to create collections of questions to organize things and decide who gets to see what in the [next section](06-collections.md).

docs/administration-guide/06-collections.md

@@ -0,0 +1,44 @@
+## Creating Collections for Your Saved Questions
+---
+
+Collections are a great way to organize your saved questions and decide who gets to see and edit things. Collections could be things like, "Important Metrics," "Marketing KPIs," or "Questions about users." Multiple user groups can be given access to the same collections, so we don't necessarily recommend naming collections after user groups.
+
+This page will teach you how to create and manage your collections. For more information on organizing saved questions and using collections, [check out this section of the User's Guide](../users-guide/05-sharing-answers.md).
+
+### Creating and editing collections
+Only administrators of Metabase can create and edit collections. From the Questions section of Metabase, click on the `Create a collection` button. Give your collection a name, choose a color for it, and give it a description if you'd like.
+
+![Permissions empty state](images/collections/collections-empty-state.png)
+
+### Setting permissions for collections
+Collection permissions are similar to data permissions. Rather than going to the Admin Panel, you set permissions on collections by clicking on the lock icon in the top-right of the Questions screen or the top-right of a collection screen.
+
+![Permissions grid](images/collections/permissions-grid.png)
+
+You'll see a table with your user groups along the top and all your collections down along the left. A user group can have View access, Curate access, or no access to a given collection.
+
+- View access: can see all the questions in the collection, **even if the user doesn't have access to the underlying data used to create the question.**
+- Curate access: can additionally move questions in or out of the collection, and edit the questions in the collection.
+- No access: won't see the collection listed on the Questions page, and can't see questions from this collection in dashboards or when creating a Pulse.
+
+Just like with data access permissions, collection permissions are *additive*, meaning that if a user belongs to more than one group, if one of their groups has a more restrictive setting for a collection than another one of their groups, they'll be given the *more permissive* setting. This is especially important to remember when dealing with the All Users group: since all users are members of this group, if you give the All Users group Curate access to a collection, then *all* users will be given that access for that collection, even if they also belong to a group with *less* access than that.
+
+### The "Everything Else" section
+If a question isn't saved within a collection, it will be placed in the Everything Else section of the main Questions page. **All your Metabase users can see questions in this section**, provided they have data access permission.
+
+### Archiving collections
+You can archive collections similarly to how you can archive questions. Click the archive icon in the top-right of the collection screen to archive it. This will also archive all questions in the collection, and importantly it will also remove all of those questions from all dashboards and Pulses that use those questions. So be careful!
+
+To restore a collection and its contents, click the `View Archive` icon in the top-right of the main Questions screen to see the archive, then hover over an item to reveal the `Unarchive` icon on the far right of the item. Questions within archived collections are not individually listed in the archive, so if you want to unarchive a specific question from an archived collection, you have to unarchive that whole collection.
+
+### What about labels?
+Older versions of Metabase provided labels as a way to organize and filter saved questions. If you were already using labels, you'll still be able to edit and use them for now from the Labels dropdown on lists of saved questions. However, **labels will be removed from Metabase in an upcoming version.** If your instance of Metabase was not using labels previously, you won't see the label tools at all anymore.
+
+What should you do if you want to prepare for the impending removal of labels? We recommend creating collections that match your most important labels, and moving the matching labeled questions into those collections.
+
+If you don't want to remove all the labels from your questions yet, we recommend at least ensuring that none of your questions have more than a single label. That way, if in the future we provide a migration tool that converts labels to collections automatically, there won't be any ambiguity with your labels.
+
+---
+
+## Next: custom segments and metrics
+Learn how to define custom segments and commonly referenced metrics in the [next section](07-segments-and-metrics.md).

docs/administration-guide/06-segments-and-metrics.md → docs/administration-guide/07-segments-and-metrics.md

@@ -47,4 +47,4 @@ Lastly, you can also view the revision history for each segment and metric from
 ---
 
 ## Next: configuring Metabase
-There are a few other settings you configure in Metabase. [Learn how](06-configuration-settings.md).
+There are a few other settings you configure in Metabase. [Learn how](08-configuration-settings.md).

docs/administration-guide/07-configuration-settings.md → docs/administration-guide/08-configuration-settings.md

@@ -19,4 +19,4 @@ This option turns determines whether or not you allow anonymous data about your
 ---
 
 ## Next: Setting up Slack
-If you want to use Slack to enhance the Metabase experience then lets do that now. Let’s learn [how to setup Slack](07-setting-up-slack.md).
+If you want to use Slack to enhance the Metabase experience then lets do that now. Let’s learn [how to setup Slack](09-setting-up-slack.md).

docs/administration-guide/08-setting-up-slack.md → docs/administration-guide/09-setting-up-slack.md

@@ -30,4 +30,4 @@ That's it!  Metabase will automatically run a quick test to check that the API t
 ---
 
 ## Next: Single Sign-On
-Learn how to [configure Single Sign-On](08-single-sign-on.md) to let users sign in or sign up with just a click.
+Learn how to [configure Single Sign-On](10-single-sign-on.md) to let users sign in or sign up with just a click.

docs/users-guide/05-sharing-answers.md

@@ -9,38 +9,39 @@ Whenever you’ve arrived at an answer that you want to save for later, click th
 
 A pop-up box will appear, you to give your question a name and a description. We suggest phrasing the names for your questions in the form of a question, such as, “How many customers did we have last month?” After saving your question, you'll be asked if you want to add it to a dashboard.
 
-Now, whenever you want to refer to your question again, you can find it in the saved questions list by clicking on the **Questions** link from the main navigation. To edit your question, go to it and click the pencil icon in the top-right.
+Now, whenever you want to refer to your question again you can find it in the saved questions list by clicking on the **Questions** link from the main navigation. To edit your question, go to it and click the pencil icon in the top-right.
 
 ### Organizing and Finding your Saved Questions
-
-
 After your team has been using Metabase for a while, you’ll probably end up with lots of saved questions. The Questions page has several tools that’ll help you organize things and find what you’re looking for.
 
 ![Questions](images/saved-questions.png)
 
-#### Shortcuts
-In the top left, you’ll find shortcuts to your favorite questions (mark a question as a favorite by clicking on the star icon that appears on the far right when you hover over it), questions you’ve recently viewed, questions that you’ve saved personally, and popular questions that are used the most by your team.
-
-#### Search
-You can search for a question by typing keywords into the **Search for a question** area.
+#### Collections
+Administrators of Metabase can create collections to put saved questions in. Depending on the permissions you've been given to collections, you'll be able to view the questions inside, edit them, and move questions from one collection to another. Questions that aren't saved in any collection will appear in the "Everything else" section of the main Questions page, and are visible to all Metabase users in your organization. If you're an administrator of your Metabase instance, here are [instructions for creating collections and managing permissions](../administration-guide/06-collections.md).
 
 #### Labels
-One great way to organize your questions is to label them. Create and organize your team’s labels by clicking on the **Labels** heading in the left menu on the Questions page. To create a label, just choose a color (or emoji!) for it, give it a name, and click **Create Label**. You can edit or delete a label by hovering of a label and clicking the **Edit** or **X** icon. You can create labels that pertain to different teams, projects, products, reports, dashboards, or whatever you want!
+Older versions of Metabase included a way to add labels to your questions, but this feature will be going away in a future version of Metabase. Currently, if your team was already using labels, you'll still be able to edit and apply them to questions. Here are some [suggestions for switching from labels to collections](../administration-guide/06-collections.md#what-about-labels).
 
-You can assign as many labels as you want to your questions. Just hover over a question in your list and click the label icon, then pick the label(s) you want to apply to the question.
+#### Shortcuts
+At the top of lists of saved questions you’ll find a dropdown with shortcuts to your favorite questions (mark a question as a favorite by clicking on the star icon that appears when you hover over it), questions you’ve recently viewed, questions that you’ve saved personally, and popular questions that are used the most by your team.
+
+#### Search and filtering
+On the main Questions page, you can search through all of your collections for a particular question using the search box in the top-right. You can also filter lists of saved questions by typing in the `Filter the list…` area.
 
-![Actions](images/question-actions.png)
+#### Moving
+To move a question into a collection, or from one collection to another, hover over it and click on the right-arrow icon that appears on the far right of the question. Note that you have to have permission to edit the collection that you're moving a question into, and the collection you're moving the question out of.
 
-If you have several questions that you want to give the same label to, just click the checkbox on the left side of each question’s title when you hover over it to select your questions, then click the Labels dropdown at the top of the page.
+#### Archiving
+Sometimes questions outlive their usefulness and need to be sent to Question Heaven. To archive a question, just click on the box icon that appears on the far right when you hover over a question. Collections can also be archived and unarchived, but only by Metabase administrators.
 
-![Checkbox](images/question-checkbox.png)
+Note that archiving a question removes it from all dashboards or Pulses where it appears, so be careful!
 
-Once you’ve created a label, it’ll appear in the list on the left side of the screen. Clicking on a label, either in the list of labels or on an individual question, will show you all the questions that have that label.
+If you have second thoughts and want to bring an archived question back, you can see all your archived questions from the **Archive** icon at the top-right of the Questions page. To unarchive a question, hover over it and click the box icon that appears on the far right.
 
-#### Archiving
-Sometimes questions outlive their usefulness and need to be sent to Question Heaven. To archive a question, just click on the box icon that appears on the far right when you hover over a question. You can also archive multiple questions the same way you apply labels to multiple questions.
+#### Selecting multiple questions
+Clicking on the icon to the left of questions let's you select several at once so that you can move or archive many questions at once.
 
-If you have second thoughts and want to bring an archived question back, you can see all your archived questions from the **Archive** link at the bottom of the left menu. To unarchive a question, hover over it and click the box icon that appears on the far right.
+![Selecting questions](images/question-checkbox.png)
 
 ---