Merge pull request #7382 from metabase/docs-for-0.29

Docs for 0.29 (WIP)

docs/administration-guide/03-metadata-editing.md

@@ -91,6 +91,13 @@ Another option is custom remapping, which is currently only possible for numeric
 
 ![Remapping form](./images/remapping/custom-mapping.png)
 
+### Picking the filter UI for a field
+
+Metabase will automatically try to pick the best kind of filter interface for each field based on that field's type and the number of different values in it. Fields with only a few possible choices, like a `Gender` field, will display a dropdown list by default when filtering on them; fields with more than 100 possible selections will show a search box with autocomplete.
+
+If Metabase picked the wrong kind of filter UI for one of your fields, you can manually change it. You can choose from a drop down list, a search box, or just a plain input box:
+
+![Filter options](./images/filter-options.png)
 
 ---
 

docs/users-guide/05-visualizing-results.md

@@ -9,6 +9,7 @@ In Metabase, an answer to a question can be visualized in a number of ways:
 * Table
 * Line chart
 * Bar chart
+* Row chart
 * Area chart
 * Scatterplot or bubble chart
 * Pie/donut chart
@@ -43,14 +44,19 @@ The Table option is good for looking at tabular data (duh), or for lists of thin
 ![Pivot table](images/visualizations/pivot.png)
 
 #### Line, bar, and area charts
-Line charts are best for displaying the trend of a number over time, especially when you have lots of x-axis values. Bar charts are great for displaying a metric grouped by a category (e.g., the number of users you have by country), and they can also be useful for showing a number over time if you have a smaller number of x-axis values (like orders per month this year).
+Line charts are best for displaying the trend of a number over time, especially when you have lots of x-axis values. Bar charts are great for displaying a number grouped by a category (e.g., the number of users you have by country), and they can also be useful for showing a number over time if you have a smaller number of x-axis values (like orders per month this year).
 
 ![Bar chart](images/visualizations/bar.png)
 
-Area charts are useful when comparing the the proportions between two metrics over time. Both bar and area charts can be stacked.
+Area charts are useful when comparing the proportions of two metrics over time. Both bar and area charts can be stacked.
 
 ![Stacked area chart](images/visualizations/area.png)
 
+#### Row charts
+If you're trying to group a number by a field that has a lot of possible values, like a Vendor or Product Title field, try visualizing it as a row chart. Metabase will show you the bars in descending order of size, with a final bar at the bottom for items that didn't fit.
+
+![Row chart](images/visualizations/row.png)
+
 ##### Histograms
 
 If you have a bar chart like Count of Users by Age, where the x-axis is a number, you'll get a special kind of chart called a **histogram**, where each bar represents a range of values (called a "bin"). Note that Metabase will automatically bin your results any time you use a number as a grouping, even if you aren't viewing a bar chart. Questions that use latitude and longitude will also get binned automatically.

docs/users-guide/08-dashboard-filters.md

@@ -29,8 +29,7 @@ Now we’ve entered a new mode where we’ll need to wire up each card on our da
 So here’s what we’re doing — when we pick a month and year with our new filter, the filter needs to know which field in the card to filter on. For example, if we have a `Total Orders` card, and each order has a `Date Ordered` as well as a `Date Delivered`, we have to pick which of those fields to filter — do we want to see all the orders *placed* in January, or do we want to see all the orders *delivered* in January? So, for each card on our dashboard, we’ll pick a date field to connect to the filter. If one of your cards says there aren’t any valid fields, that just means that card doesn’t contain any fields that match the kind of filter you chose.
 
 #### Filtering SQL-based cards
-Note that if your dashboard includes cards that were created using the SQL/native query editor, you'll need to add a bit of additional markup to the SQL in those cards in order to use a dashboard filter on them. [Using SQL parameters](13-sql-parameters.md)
-
+**Important:** note that if your dashboard includes saved questions that were created using the SQL/native query editor, you'll need to [add a bit of additional markup to your query](13-sql-parameters.md) to add a "field filter variable" in order to use a dashboard filter with your SQL/native questions.
 
 ![Select fields](images/dashboard-filters/04-select-fields.png)
 
@@ -58,6 +57,24 @@ Once you’ve added a filter to your dashboard, just click on it to select a val
 
 ![Using a filter](images/dashboard-filters/08-use-filter.png)
 
+### Choosing between a dropdown or autocomplete for your filter
+
+Picking selections for a filter with lots of options is easier than ever before. If the field you're using for a filter has more than 100 unique values, you'll now automatically see a search box with autocomplete suggestions.
+
+![Autocomplete](images/dashboard-filters/autocomplete.png)
+
+Fields with fewer than 100 distinct values will have display a list of all the options.
+
+![List](images/dashboard-filters/list.png)
+
+In both cases, you can pick one or multiple selections for your filter.
+
+![Multi-select](images/dashboard-filters/multi-select.png)
+
+If Metabase somehow picked the wrong behavior for your field, admins can go to the Data Model section of the admin panel and click on the gear icon by the field in question to manually choose between a list, a search box, or just a plain input box.
+
+![Search options](images/dashboard-filters/search-options.png)
+
 ### Best practices
 
 Here are a few tips to get the most out of dashboard filters:

docs/users-guide/10-pulses.md

 
-## Sharing Updates with Pulses
+## Sharing updates with pulses
 The Pulses feature in Metabase gives you the ability to automatically send regular updates to your teammates to help everyone keep track of changes to the metrics that matter to you most. You can deliver a pulse via email or [Slack](https://slack.com/), on the schedule of your choice.
 
-You can create a pulse and view all of the existing pulses by clicking the `Pulses` link from the top menu. Click `Create a pulse` to get started.
+Click the `Pulses` link in the top menu to view all of your pulses, and click `Create a pulse` to make a new one.
 
 ![Create a pulse](images/pulses/01-empty-state.png)
 
-### Name It
+### Name it
 First, choose a name for your pulse. This will show up in the email subject line and the Slack message title, so choose something that will let people know what kind of updates the pulse will contain, like “Daily Marketing Update,” or “Users Metrics.”
 
 ![Giving it a name](images/pulses/02-name-it.png)
 
-### Pick Your Data
-Before you can create a pulse, you’ll need to have some [saved questions](06-sharing-answers.md). You can choose up to five of them to put into a single pulse. Click the dropdown to see a list of all your saved questions. You can type in the dropdown to help filter and find the question you’re looking for.
+### Pick your data
+Before you can create a pulse, you’ll need to have some [saved questions](06-sharing-answers.md). Click the dropdown to see a list of all your saved questions. You can type in the dropdown to help filter and find the question you’re looking for.
 
 ![Pick your data](images/pulses/03-pick-your-data.png)
 
@@ -20,6 +20,10 @@ When you select a saved question, Metabase will show you a preview of how it’l
 
 ![Behold! The metamorphosis.](images/pulses/04-transformation.png)
 
+Now you can include tables in your pulses as well. They'll be capped to 10 columns and 20 rows, and for emailed pulses the rest of the results will be included automatically as a file attachment, with a limit of 2,000 rows.
+
+![Table in pulse](images/pulses/table.png)
+
 #### Attaching a .csv or .xls with results
 You can also optionally include the results of a saved question in an emailed pulse as a .csv or .xls file attachment. Just click the paperclip icon on an included saved question to add the attachment. Click the paperclip again to remove the attachment.
 
@@ -36,12 +40,12 @@ Your attachments will be included in your emailed pulse just like a regular emai
 #### Limitations
 Currently, there are a few restrictions on what kinds of saved questions you can put into a pulse:
 
-* Raw data questions won't be displayed, but will be included as a file attachment
-* Pivot tables will be cropped to a maximum of three columns and 10 rows
-* Bar charts (and pie charts which get turned into bar charts) will be cropped to one column for the labels, one column for the values, and 10 total rows
+* Raw data questions are capped to 10 columns and 20 rows. For emailed pulses, the rest of the results will be included automatically as a file attachment, with a limit of 2,000 rows.
+* Pivot tables will be cropped to a maximum of three columns and 10 rows.
+* Bar charts (and pie charts which get turned into bar charts) will be cropped to one column for the labels, one column for the values, and 10 total rows.
 
-### Choose How and When to Deliver Your Data
-Each pulse you create can be delivered by email, Slack, or both. You can also set a different delivery schedule for email versus Slack. To deliver by email, just type in the email addresses you want to send the pulse to, separated by commas. Then, choose to either send it daily, weekly, or monthly, and the time you want it to be sent.
+### Choose how and when to deliver your data
+Each pulse you create can be delivered by email, Slack, or both. You can also set a different delivery schedule for email versus Slack. To deliver by email, just type in the Metabase user names, or email addresses you want to send the pulse to, separated by commas. Then, choose to either send it daily, weekly, or monthly, and the time at which you want it to be sent.
 
 ![Setting the email schedule](images/pulses/05-email-schedule.png)
 

docs/users-guide/14-x-rays.md

-## X-rays and Comparisons
+## X-rays
 ---
-X-rays and comparisons are two powerful new features in Metabase that allow you to get deeper statistical reports about your segments, fields, and time series.
+X-rays are a fast and easy way to get automatic insights and explorations of your data.
 
-### Time series x-rays
+### Exploring newly added datasets
 
-To view an x-ray report for a time series, open up a saved time series question (any kind of chart or table with a metric broken out by time), click on the Action Menu in the bottom-right of the screen, and select "X-ray this question:"
+When you first connect a database to Metabase, Metabot will offer to show you some automated explorations of your data.
 
-![Time series x-ray action](images/x-ray-action-time-series.png)
+![X-ray example](.images/x-rays/suggestions.png)
 
-You'll get an in-depth analysis of your time series question, including growth rates, the distribution of values, and seasonality:
+Click on one of these to see an x-ray.
 
-![Time series x-ray](images/x-ray-time-series.png)
+![X-ray example](.images/x-rays/example.png)
 
-### Segment, table, and field x-rays
-To view an x-ray for a segment, table, or field, first go to the Data Reference, then navigate to the thing you want to x-ray, then select the x-ray option in the lefthand menu:
+You can see more suggested x-rays over on the right-hand side of the screen. If you come across an x-ray that's particularly interesting, you can save it as a dashboard by clicking the green Save button.
 
-![X-rays in data reference](images/x-ray-data-reference.png)
+### Creating x-rays by clicking on charts or tables
 
-If you have a saved Raw Data question that uses one or more segments as filters, you can also x-ray one of those segments from the Action Menu in the bottom-right of the screen when viewing that question:
+One great way to explore your data in general in Metabase is to click on points of interest in charts or tables, which shows you ways to further explore that point. We've added x-rays to this action menu, so if you for example find a point on your line chart that seems extra interesting, give it a click and x-ray it! We think you'll like what you see.
 
-![X-ray action](images/x-ray-action.png)
+![X-ray action in drill-through menu](.images/x-rays/drill-through.png)
 
-An x-ray report for a segment called "Californians" looks like this, displaying a summary of the distribution of values for each field in the segment, and the maximal and minimal values if applicable:
+### X-rays in the Data Reference
 
-![X-ray](images/x-ray.png)
+You can also create an x-ray by navigating to a table, field, metric, or segment in the [Data Reference](./12-data-model-reference.md). Just click the x-ray link in the left sidebar.
 
-Clicking on the summary for any field will take you to the detailed x-ray report for that single field.
+![Data Reference x-ray](.images/x-rays/data-reference.png)
 
-### Changing the fidelity of an x-ray
+### Where did the old x-rays go?
 
-X-rays can be a somewhat costly or slow operation for your database to run, so by default Metabase only does a quick sampling of the segment or field you're x-raying. You can increase the fidelity in the top-right of the x-ray page:
-
-![X-ray fidelity](images/x-ray-fidelity.png)
-
-Administrators can also set the maximum allowed fidelity for x-rays in the Admin Panel. Note that the `Extended` setting is required for time series x-rays to work. Admins can even turn x-rays off entirely, but that makes Simon cry. No one likes it when Simon cries.
-
-### Comparing segments
-
-Segments are a subset of a larger table or list, so one thing you can do when viewing an x-ray of a segment is compare it to its "parent" table. For example, if I have a segment called "Californians," which is a subset of the "People" table, I can click on the button that says "Compare to all People" to see a comparison report:
-
-![Compare](images/x-ray-compare-button.png)
-
-The comparison report shows how many rows there are in the segment versus the parent table, and also gives you a breakdown of how the fields in the segment differ from that of the parent table:
-
-![Comparison report](images/x-ray-comparison.png)
-
-An example for where this can be especially useful is a scenario where you've defined many different segments for your users or customers, like "Repeat Customers," "Users between 18 and 35," or "Female customers in Kalamazoo who dislike cheese." You can open up the x-ray for any of these segments, and then compare them to the larger Users or Customers table to see if there are any interesting patterns or differences.
-
-## Automated insights
-Metabase hasn't quite achieved self-awareness, but it has gotten smarter recently. It will now show you relevant insights about your data at the top of x-rays about time series or numeric fields, provided there's something insightful to say.
-
-![Insights](./images/insights.png)
-
-Insights include things like whether or not your data has an overall trend, has uncharacteristic spikes or dips, or if it follows a similar pattern at regular intervals.
+We're reworking the way we do things like time series growth analysis and segment comparison, which were present in the previous version of x-rays. In the meantime, we've removed those previous x-rays, and will bring those features back in a more elegant and streamlined way in a future version of Metabase.
 
 ## Need help?
 If you still have questions about x-rays or comparisons, you can head over to our [discussion forum](http://discourse.metabase.com/). See you there!