Beefed up modeling intro section of docs and added Markdown page.

getguesstimate · Aug 18, 2016 · 38b23d2 · 38b23d2
1 parent 97a9a42
commit 38b23d2
Show file tree

Hide file tree

Showing 9 changed files with 71 additions and 6 deletions.
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -8,7 +8,8 @@
 * [Modeling](basic_modeling/README.md)
   * [Input Types](basic_modeling/input_types.md)
   * [Interpreting Your Results](basic_modeling/interpreting_your_results.md)
-  * [SIPS and SLURPS](basic_modeling/sips_and_slurps.md)
+  * [SIPs and SLURPs](basic_modeling/sips_and_slurps.md)
+  * [Markdown](basic_modeling/markdown.md)
 * [Function Reference](functions/README.md)
   * [Operators](functions/operators.md)
   * [Available Functions](functions/existing_functions.md)

diff --git a/assets/Canvas Toolbar.png b/assets/Canvas Toolbar.png
diff --git a/assets/Canvas.png b/assets/Canvas.png
diff --git a/assets/Description Form.png b/assets/Description Form.png
diff --git a/assets/Documentation Widget Open.png b/assets/Documentation Widget Open.png
diff --git a/assets/Metric.png b/assets/Metric.png
diff --git a/basic_modeling/README.md b/basic_modeling/README.md
@@ -1,6 +1,56 @@
-## Modeling
+# Modeling
+### The Canvas
+![The Guesstimate Canvas](../assets/Canvas.png)
+The guesstimate canvas is the environment in which all Guesstimate models are made. It is a grid of cells, similar to a
+spreadsheet, and each empty cell can be filled with a metric (see below). There are several aspects to the canvas:
 
-* [Input Types](input_types.md)
-* [Interpreting Your Results](interpreting_your_results.md)
-* [SIPS and SLURPS](sips_and_slurps.md)
+#### Documentation Widget
+The documentation widget is located along the right edge of the canvas. Clicking on the documenation widget opens a
+documentation sidebar, giving quick access for modelling help.
+![The Documentaiton Sidebar](../assets/Documentation Widget Open.png)
 
+#### Canvas Toolbar
+The canvas toolbar sits just beneath the model name, and contains menus and buttons to take various actions on the
+model or selected metrics.
+
+![The Canvas Toolbar](../assets/Canvas Toolbar.png)
+
+The buttons are (from left to right):
+
+| Name             | Description                                                                                                         | Keyboard Shortcut                    |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| File Menu        | Has nested options for copying or deleting the model entirely, and importing [SIPs and SLURPs](sips_and_slurps.md). | N/A                                  |
+| View Menu        | Has nested options to toggle different view states and turn on or off arrows.                                       | N/A                                  |
+| Cut Button       | Cuts (copies, then deletes) all currently selected metrics                                                          | ctrl/cmd - x                         |
+| Copy Button      | Copies all currently selected metrics                                                                               | ctrl/cmd - c                         |
+| Paste Button     | Pastes the currently copied region onto the selected cell.                                                          | ctrl/cmd - v                         |
+| Delete Button    | Deletes all currently selected metrics                                                                              | del/bksp                             |
+| Undo Button      | Undoes the most recent change to the model                                                                          | ctrl/cmd - z                         |
+| Redo Button      | Redoes the most recently undone change to the model                                                                 | ctrl/cmd - shift - z or ctrl/cmd - y |
+| Calculator Menu  | Allows you to view and create calculators off this model                                                            | N/A                                  |
+
+On the far right of the toolbar (not shown above) is a dropdown menu to toggle view mode or edit mode. In view mode, you
+can interact with the model, but changes will not be saved, whereas in edit mode, changes will be saved.
+
+#### The Model Description
+The model description allows you to describe a model in more detail than just the name. Here, you can include citation,
+long-form explanations, images, or links to more information. The description is edited in [Markdown](markdown.md). To
+open the description, click on the 'right arrow' button on the left side, at which point you will see a form where you
+can edit the description.
+
+![Description Form](../assets/Description Form.png)
+
+### Metrics
+You can fill canvas cells with _metrics_. A metric can have a name, description, and a value.
+
+![Metric](../assets/Metric.png)
+
+To create a metric, simply double click on any empty cell in the canvas.
+
+Metric names are used for reference, and their descriptions (which, like model descriptions, use
+[Markdown](markdown.md)) can provide sources or additional context around a metric value.
+
+Metric values can be of several different types. These are explored in more detail [here](input_types.md).
+
+The metric card will report information about the value of that metric. For help interpreting these results, see
+[here](interpreting_your_results.md).
diff --git a/basic_modeling/input_types.md b/basic_modeling/input_types.md
@@ -1,6 +1,6 @@
 # Input Types
 
-Guesstimate cells support several diferent types of inputs.
+Metrics support several diferent types of inputs.
 
 #### Point Values
 

diff --git a/basic_modeling/markdown.md b/basic_modeling/markdown.md
@@ -0,0 +1,14 @@
+## Introduction to Markdown
+
+Markdown is a text-based language designed to make it easy for you to express rich, meaningful content using only text.
+
+Here are some examples of markdown syntax:
+
+| Expression                          | Description                                                             | output                                  |
+| ----------------------------------- | ----------------------------------------------------------------------- | --------------------------------------- |
+| \[hi\]\(www.google.com\)            | A link to [`www.google.com`](www.google.com) that displays as text 'hi' | [hi](www.google.com)                    |
+| !\[Image\]\(https://goo.gl/huNep2\) | Shows the image at URL `https://goo.gl/huNep2`                          | ![Image](https://goo.gl/huNep2)         |
+| \* Item 1<br> \* Item 2             | A bulleted list with two elements                                       | <ul><li>Item 1</li><li>Item 2</li></ul> |
+| \`Code Block\`                      | A code block                                                            | `Code Block`                            |
+
+For more information on Markdown, see [here](https://guides.github.com/features/mastering-markdown/).