Improving Overview

packages/website/docs/Discussions/Future-Features.md

@@ -3,23 +3,15 @@ title: Future Features
 sidebar_position: 3
 ---
 
-Squiggle is still very early. The main first goal is to become stable. This means having a clean codebase, having decent test coverage, and having a syntax we are reasonably confident in. Later on, there are many other features that will be interesting to explore.
+Squiggle is still very early. The main first goal is to become stable (to reach version 1.0). Right now we think it is useable to use for small projects, but do note that there are very likely some math bugs and performance problems.
 
 ## Programming Language Features
 
-- Equality (a == b)
-- If/else statements
-- Arrays
 - Tables / Matrices
-- Simple objects
 - A simple type system
-- Simple module system (`Dist.Normal` instead of `normal`)
 - A simple time library & notation
 - Optional and default paramaters for functions
-- Anonymous Functions (This is particularly convenient in cases where tiny functions are submitted in forecasting competitions)
 - A notation to limit the domain of functions. For example, maybe a function only applies for t=[2 to 20]
-- Custom parser (Right now we're using Math.js's parser, which doesn't give us much flexibility)
-- "Partial-domain" distributions. For example, maybe someone has a distribution for when AGI will happen, but doesn't want to make any estimates past 2200.
 
 ## Distribution Features
 
@@ -34,12 +26,6 @@ Takes a distribution and smoothens it. For example, [Elicit Forecast](https://fo
 **Probabilities**  
 Right now Squiggle mostly works with probability distributions only, but it should also work smoothly with probabilities.
 
-**Scoring**  
-Have functions to score probabilities, probability distributions, and functions that return probability distributions.
-
-**Full javascript library**  
-A full Javascript library that accesses most of the probabilistic functionality of Squiggle, but can be used directly in javascript functions.
-
 **Importance & quality scores**  
 Workflows/functionality to declare the importance and coveredness of each part of the paramater space. For example, some subsets of the paramater space of a function might be much more important to get right than others. Similarly, the analyst might be much more certain about some parts than others. Ideally. they could decline sections.
 
@@ -52,12 +38,6 @@ Of course, we'd also need good math for how the scoring should work, exactly.
 
 This interface should also be able to handle changing Squiggle values. This is because people would be likely to want to update their functions over time, and that should be taken into account for scoring.
 
-**Easily call other functions**  
-It would be great to be able to call other people's Squiggle functions, from other Squiggle functions. This could raise a whole bunch of challenging issues. Additionally, it would be neat to call other data, both from knowledge graphs, and from regular APIs. Note that this could obviously complicate scoring a lot; I imagine that either easy scoring, or simple data fetching, would have to accept sacrifices.
-
-**Correlated uncertainties**  
-Right now there's no functionality to declare that two different distributions are correlated.
-
 **Static / Sensitivity Analysis**  
 Guesstimate has Sensitivity analysis that's pretty useful. This could be quite feasible to add, though it will likely require some thinking.
 
@@ -70,15 +50,6 @@ Right now, Monte Carlo simulations are totally random. It would be nicer to be a
 ## Major Standard Language Features
 
 - Some testing story.
-- A custom code highlighting format.
-- Possibly a decent web GUI (a much more advanced playground).
-- A VS Code extention and similar.
-
-## Bugs
-
-- Discrete distributions are particularly buggy. Try `mm(1,2,3,4,5,6,7,8,9,10) .* (5 to 8)`
-
-## New Functions
 
 ### Distributions
 
@@ -87,20 +58,3 @@ cauchy();
 pareto();
 metalog();
 ```
-
-Possibly change mm to mix, or mx(). Also, change input format, maybe to mx([a,b,c], [a,b,c]).
-
-### Functions
-
-```js
-samples(distribution, n);
-toPdf(distribution);
-toCdf(distribution);
-toHash(distribution);
-trunctate(distribution, leftValue, rightValue);
-leftTrunctate(distribution, leftValue);
-rightTrunctate(distribution, rightValue);
-distributionFromSamples(array, params);
-distributionFromPoints();
-distributionFromHash();
-```

packages/website/docs/Guides/Language.mdx

@@ -47,6 +47,19 @@ f`}
 
 <SquiggleEditor defaultCode={`{|t| normal(t^2, t^1.2+.01)}`} />
 
+### Comments
+
+<SquiggleEditor defaultCode={`// This is a single-line comment
+/*
+This is a multiple
+-line comment.
+*/
+`} />
+
+### Pipes
+
+<SquiggleEditor defaultCode={`normal(5,2) |> truncateLeft(3) |> SampleSet.fromDist`} />
+
 ## See more
 
 - [Distribution creation](./DistributionCreation)

packages/website/docs/Introduction.md

@@ -1,30 +0,0 @@
----
-sidebar_position: 1
-title: Introduction
----
-
-Squiggle is a simple programming language for intuitive probabilistic estimation. It's meant for quantitative forecasting and evaluations.
-
-The basics of Squiggle can be pretty simple and intuitive. The more advanced functionality can take some time to learn.
-
-## What Squiggle Is
-
-- A simple programming language for doing math with probability distributions
-- An embeddable language that can be used in Javascript applications
-- A tool to embed functions as forecasts that can be embedded in other applications
-
-## What Squiggle Is Not
-
-- A complete replacement for enterprise Risk Analysis tools (See Crystal Ball, @Risk, Lumina Analytica)
-- A Probabilistic Programming Language with backwards inference and sophisticated sampling algorithms. (See [PPLs](https://en.wikipedia.org/wiki/Probabilistic_programming))
-- A visual tool aimed at casual users (see Guesstimate, Causal)
-
-## Get started
-
-- [Gallery](./Discussions/Gallery)
-- [Squiggle playground](/playground)
-- [Language basics](./Guides/Language)
-- [Squiggle functions source of truth](./Guides/Functions)
-- [Known bugs](./Discussions/Bugs)
-- [Original lesswrong sequence](https://www.lesswrong.com/s/rDe8QE5NvXcZYzgZ3)
-- [Author your squiggle models as Observable notebooks](https://observablehq.com/@hazelfire/squiggle)

packages/website/docs/Overview.md

@@ -0,0 +1,68 @@
+---
+sidebar_position: 1
+title: Overview
+---
+
+Squiggle is a minimalist programming language for probabilistic estimation. It's meant for intuitively-driven quantitative estimation instead of data analysis or data-driven statistical techniques.
+
+The basics of Squiggle are fairly straightforward. This can be enough for many models. The more advanced functionality can take some time to learn.
+
+## Using Squiggle
+You can currently interact with Squiggle in a few ways:
+
+**[Playground](/playground)**  
+The [Squiggle Playground](/playground) is a nice tool for working with small models and making prototypes. You can make simple sharable links, but you can't save models that change over time.
+
+**[Typescript Library](https://www.npmjs.com/package/@quri/squiggle-lang)**  
+Squiggle is built using [Rescript](https://rescript-lang.org/), and is accessible via a simple Typescript library. You can use this library to either run Squiggle code in full, or to call select specific functions within Squiggle (though this latter functionality is very minimal). 
+
+**[React Components Library](https://www.npmjs.com/package/@quri/squiggle-components)**  
+All of the components used in the playground and documentation are available in a separate component NPM repo. You can see the full Storybook of components [here](https://squiggle-components.netlify.app).
+
+**[Visual Studio Code Extension](https://marketplace.visualstudio.com/items?itemName=QURI.vscode-squiggle)**  
+There's a simple [VS Code extension](https://marketplace.visualstudio.com/items?itemName=QURI.vscode-squiggle) for running and visualizing Squiggle code. We find that VS Code is a useful editor for managing larger Squiggle setups.
+
+## Squiggle Vs. Other Tools
+
+### What Squiggle Is
+
+- A simple programming language for doing math with probability distributions.
+- An embeddable language that can be used in Javascript applications.
+- A tool to encode functions as forecasts that can be embedded in other applications.
+
+### What Squiggle Is Not
+
+- A complete replacement for enterprise Risk Analysis tools. (See [Crystal Ball](https://www.oracle.com/applications/crystalball/), [@Risk](https://www.palisade.com/risk/), [Lumina Analytica](https://lumina.com/))
+- A [probabilistic programming language](https://en.wikipedia.org/wiki/Probabilistic_programming). Squiggle does not support Bayesian inference.
+- A tool for substantial data analysis. (See programming languages like [Python](https://www.python.org/) or [Julia](https://julialang.org/))
+- A programming language for anything other than estimation.
+- A visually-driven tool. (See [Guesstimate](https://www.getguesstimate.com/) and [Causal](https://causal.app/))
+
+### Strengths
+- Simple and readable syntax, especially for dealing with probabilistic math.
+- Fast for relatively small models. Strong for rapid prototyping.
+- Optimized for using some numeric and symbolic approaches, not just Monte Carlo. 
+- Embeddable in Javascript.
+- Free and open-source.
+
+### Weaknesses 
+- Limited scientific capabilities.
+- Much slower than serious probabilistic programming languages on sizeable models.
+- Can't do Bayesian backwards inference.
+- Essentially no support for libraries or modules (yet).
+- Still very new, so a tiny ecosystem.
+- Still very new, so there are likely math bugs.
+- Generally not as easy to use as Guesstimate or Causal, especially for non programmers.
+
+## Organization
+Squiggle is one of the main projects of [The Quantified Uncertainty Research Institute](https://quantifieduncertainty.org/). QURI is a nonprofit funded primarily by [Effective Altruist](https://www.effectivealtruism.org/) donors.
+
+## Get started
+
+- [Gallery](./Discussions/Gallery)
+- [Squiggle playground](/playground)
+- [Language basics](./Guides/Language)
+- [Squiggle functions source of truth](./Guides/Functions)
+- [Known bugs](./Discussions/Bugs)
+- [Original lesswrong sequence](https://www.lesswrong.com/s/rDe8QE5NvXcZYzgZ3)
+- [Author your squiggle models as Observable notebooks](https://observablehq.com/@hazelfire/squiggle)

packages/website/docusaurus.config.js

@@ -61,7 +61,7 @@ const config = {
         items: [
           {
             type: "doc",
-            docId: "Introduction",
+            docId: "Overview",
             position: "left",
             label: "Documentation",
           },
@@ -83,6 +83,11 @@ const config = {
             label: "GitHub",
             position: "right",
           },
+          {
+            href: "https://quantifieduncertainty.org/",
+            label: "QURI",
+            position: "right",
+          },
         ],
       },
       footer: {

packages/website/sidebars.js

@@ -23,8 +23,8 @@ const sidebars = {
   tutorialSidebar: [
     {
       type: "doc",
-      id: "Introduction",
+      id: "Overview",
-      label: "Introduction",
+      label: "Overview",
     },
     {
       type: "doc",