Incorporate feedback from Mark (#550)

* Feedback from Mark

* Small Connect fixes

* Update smart contract language

* fixing principals explanation

* Typos + stablecoin

* Update overview.md

_core/smart/overview.md

@@ -13,31 +13,34 @@ Clarity is a smart contracting language for use with the Stacks 2.0 blockchain.
 
 ## Smart contracts
 
+Smart contracts encode and enforce the rules for modifying a particular set of data as shared among people and entities who don't necessarily trust each other. For example, a smart contract could allow creators to add a new tv show to a streaming service, but require that users first pay for a decryption key before viewing it. To do this, the smart contract could be written such that the movie creator had to publicly disclose the decryption key in order to receive payment. The movie creators would therefore be incentivized to work on tv show episodes that people want to watch, based on the viewers' upfront payments that are locked-in until the creator releases the episode and the decryption key.
 
-Smart contracts encode and enforce the rules for curating this data, and are often used to ensure that users can exchange valuable data in an automated and secure way. For example, a smart contract could allow anyone to add a new movie to a movie catalog, but require that someone first pay for a decryption key before anyone can view it. To do this, the smart contract could be written such that the movie creator had to publicly disclose the decryption key in order to receive payment. Such a system would allow movie creators to make money by adding movies to the movie catalog that people want to watch.
+Because smart contracts run on top of a blockchain, anyone can query them, and anyone can submit transactions to execute them. A smart contract execution can result in new transactions being written to the blockchain.
 
-Because smart contracts run on top of a blockchain, anyone can query them, and anyone can submit transactions to run their code. The blockchain stores the history of all accepted transactions, so anyone can audit the blockchain in order to independently verify that an app's global shared state has been managed correctly according to the smart contract's rules.
+Apps use the blockchain to manage a global state that is visible to the public. To get back to the streaming service example, the global state could include a list of user that paid for a specific tv show episode. This is possible because the blockchain stores the history of all accepted transactions.
+
+Anyone can audit the blockchain in order to independently verify that an app's global shared state has been managed correctly according to the smart contract's rules.
 
 ## Use cases
 
 Not every decentralized application requires smart contracts, but Clarity unlocks interesting capabilities for decentralized applications. Examples of use cases include, but are not limited to:
 
 * Access control (e.g. pay to access)
-* Non-fungible and fungible tokens
+* Non-fungible (e.g. collectibles) and fungible tokens (e.g. stablecoins)
 * Business model templates (e.g. subscriptions)
 * App-specific blockchains
 * Decentralized Autonomous Organizations
 
 ## Language design
 
-Clarity is a [list processing (LISP) language](https://en.wikipedia.org/wiki/Lisp_(programming_language)) and differs from most other smart contract languages in two essential ways:
+Clarity differs from most other smart contract languages in two essential ways:
 
 * The language is interpreted and broadcasted on the blockchain as is (not compiled)
 * The language is decidable (not Turing complete)
   
-Using an interpreted language ensures that the code that executes is human-readable, and is auditable by users. The fact that Clarity is a decidable language means that users can determine the set of reachable code from any function they want to call.
+Using an interpreted language ensures that the executed code is human-readable and auditable. A decidable language like Clarity makes it possible to determine precisely which code is going to be executed, for any function.
 
-A Clarity smart contract is composed of two parts — a data-space and a set of functions. Only the associated smart contract may modify its corresponding data-space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. Users call smart contracts' public functions by broadcasting a transaction on the blockchain which invokes the public function. Contracts can also call public functions from other smart contracts.
+A Clarity smart contract is composed of two parts — a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. Users call smart contracts' public functions by broadcasting a transaction on the blockchain which invokes the public function. Contracts can also call public functions from other smart contracts.
 
 Note some of the key Clarity language rules and limitations.
 

_core/smart/principals.md

@@ -6,7 +6,7 @@ permalink: /:collection/:path.html
 # Principals
 {:.no_toc}
 
-_Principals_ are a Clarity native type that represents a spending entity. This section discusses principals and how they are used in the Clarity.  
+_Principals_ are a Clarity native type that represents an entity that can have a token balance. This section discusses principals and how they are used in the Clarity.
 
 * TOC
 {:toc}

_core/smart/tutorial-counter.md

@@ -19,7 +19,7 @@ In this tutorial, you learn how to implement a smart contract that stores and ma
 * TOC
 {:toc}
 
-## Pre-requisites
+## Prerequisites
 
 Before you get started, you should complete the [Hello World tutorial](tutorial.html).
 
@@ -100,11 +100,13 @@ Let's get familiar with the tests to understand what the new smart contract shou
 
     The first line initializes a new integer variable `counter` with the value set to `0` using the [`define-data-var`](https://docs.blockstack.org/core/smart/clarityref#define-data-var) statement. It is important to note that all definition statements in Clarity need to be at the top of the file.
 
+    The `counter` variable is stored in the data space associated with this particular smart contract. The variable is persisted and acts as the global shared state.
+
     To provide access to the `counter` variable from outside of the current smart contract, we need to declare a public function to get it. The last lines of the code add a public `get-counter` function. The [`var-get`](https://docs.blockstack.org/core/smart/clarityref#var-get) statement looks for a variable in the contract's data space and returns it.
 
     With that, you are ready to rerun the tests!
 
-1. Run the tests and review the results:
+3. Run the tests and review the results:
 
     ```shell
     npm test
@@ -114,7 +116,7 @@ Let's get familiar with the tests to understand what the new smart contract shou
 
     However, we don't stop here. Let's implement increment and decrement functions.
 
-2. Add the following lines to the bottom of the `counter.clar` file and take a few seconds to review them:
+4. Add the following lines to the bottom of the `counter.clar` file and take a few seconds to review them:
 
     ```cl
     (define-public (increment)
@@ -127,7 +129,7 @@ Let's get familiar with the tests to understand what the new smart contract shou
 
     Next, a [`var-set`](https://docs.blockstack.org/core/smart/clarityref#var-set) is used to set a new value for the `counter` variable. The new value is constructed using the [`+`](https://docs.blockstack.org/core/smart/clarityref#-add) (add) statement. This statement takes a number of integers and returns the result. Along with add, Clarity provides statements to subtract, multiply, and divide integers. Find more details in the [Clarity language reference](https://docs.blockstack.org/core/smart/clarityref).
 
-3. Finally, take a few minutes and implement a new public function `decrement` to subtract `1` from the `counter` variable. You should have all knowledge needed to succeed at this!
+5. Finally, take a few minutes and implement a new public function `decrement` to subtract `1` from the `counter` variable. You should have all knowledge needed to succeed at this!
 
     Done? Great! Run the tests and make sure all of them are passing. You are looking for 4 passed tests:
 
@@ -145,7 +147,7 @@ Let's get familiar with the tests to understand what the new smart contract shou
 
     **Congratulations! You just implemented your first Clarity smart contract.**
 
-4. Here is how the final smart contract file should look like. Note that you can find the `decrement` function in here - in case you want to compare with your own implementation:
+6. Here is how the final smart contract file should look like. Note that you can find the `decrement` function in here - in case you want to compare with your own implementation:
 
     ```cl
     (define-data-var counter int 0)

_core/smart/tutorial.md

@@ -20,7 +20,7 @@ In this tutorial, you learn how to use Clarity, Blockstack's smart contracting l
 * TOC
 {:toc}
 
-## Pre-requisites
+## Prerequisites
 
 To complete the tutorial, you should have [NodeJS](https://nodejs.org/en/download/) installed on your workstation. To install and run the starter project, you need to have at least version `8.12.0`. You can verify your installation by opening up your terminal and run the following command:
 
@@ -90,7 +90,7 @@ Now, let's have a look at a Clarity smart contract and get familiar with the bas
       (ok val))
     ```
 
-    On the first line, a new public function `say-hi` is declared. To create private functions, you would use the `define-private` keyword. Private functions can only be executed by the current smart contract and not from the outside. Only public functions can be called from outside, by other smart contracts. The reason public functions exist is to enable re-using code that is already available in other smart contracts, and to enable developers to break complex smart contracts into smaller, simpler smart contracts (an exercise in [separating concerns](https://en.wikipedia.org/wiki/Separation_of_concerns)).
+    On the first line, a new public function `say-hi` is declared. To create private functions, you would use the `define-private` keyword. Private functions can only be executed by the current smart contract - not from other smart contracts published to the same network. Only public functions can be called from other contracts. The reason public functions exist is to enable re-using code that is already available in other smart contracts, and to enable developers to break complex smart contracts into smaller, simpler smart contracts (an exercise in [separating concerns](https://en.wikipedia.org/wiki/Separation_of_concerns)).
 
     The function doesn't take any parameters and simply returns "hello world" using the [`ok`](https://docs.blockstack.org/core/smart/clarityref#ok) response constructor.
 
@@ -146,9 +146,9 @@ Note that we're importing modules from the `@blockstack/clarity` package:
 import { Client, Provider, ProviderRegistry, Result } from "@blockstack/clarity";
 ```
 
-### Initiliazing a client
+### Initializing a client
 
-At the test start, we are initializing contract instance `helloWorldClient` and a provider that simulates interactions with the Stacks 2.0 blockchain.
+At the test start, we are initializing a contract instance `helloWorldClient` and a provider that simulates interactions with the Stacks 2.0 blockchain. If this were in a production environment, the contract instance would be the equivalent of a contract deployed to the blockchain. The provider would be the Stacks blockchain.
 
 ```js
 let helloWorldClient: Client;

_develop/connect/get-started.md

@@ -2,9 +2,10 @@
 layout: learn
 permalink: /:collection/:path.html
 ---
-# Get Started
+# Guide to Blockstack Connect
 {:.no_toc}
 
+
 Blockstack Connect is a Javascript library for integrating your application with Stacks v2. With Connect, you get some big benefits:
 
 <!-- -  -->

_develop/connect/overview.md

@@ -2,7 +2,7 @@
 layout: learn
 permalink: /:collection/:path.html
 ---
-# Overview
+# Introduction
 {:.no_toc}
 
 * TOC
@@ -22,4 +22,8 @@ To get a test feel for the user experience of using Connect, you can use [Banter
 
 Although [`blockstack.js`](https://github.com/blockstack/blockstack.js) exposes everything you need to handle authentication with Blockstack, there is still the hard problem of getting users familiar with the the paradigm of authentication that is privacy-first and self-sovereign. Many apps implement their own dialogues before authentication, which explain what Blockstack is and why they use it.
 
-`@blockstack/connect` provides developers with a plug-and-play API that is simple to use, and provides great, out-of-the-box education that end-users can understand.
+`@blockstack/connect` provides developers with a plug-and-play API that is simple to use, and provides great, out-of-the-box education that end-users can understand.
+
+## How can this be used?
+
+Head over to the [Guide to Connect](get-started.html) for installation steps and usage guidelines.

_develop/connect/use-with-clarity.md

@@ -2,7 +2,7 @@
 layout: learn
 permalink: /:collection/:path.html
 ---
-# Usage with Clarity
+# Signing transactions
 {:.no_toc}
 
 With Connect, you can interact with the Stacks 2.0 blockchain. You can allow your users to send transactions and interact with smart contracts.

_develop/profiles.md

@@ -21,16 +21,12 @@ Profile data is stored using Gaia on the user's selected storage provider. An ex
 https://gaia.blockstack.org/hub/1EeZtGNdFrVB2AgLFsZbyBCF7UTZcEWhHk/profile.json
 ```
 
-
 Follow these steps to create and register a profile for a Blockstack ID:
 
 1. Create a JSON profile object
 2. Split up the profile into tokens, sign the tokens, and put them in a token file
 3. Create a zone file that points to the web location of the profile token file
 
-
-Accounts can have one or more proofs. Proofs are stored under the `account` key in the user's profile data
-
 ```js
 "account": [
 	{
@@ -88,63 +84,4 @@ const recoveredProfile = Person.fromToken(tokenFile, publicKey)
 
 ```js
 const validationResults = Person.validateSchema(recoveredProfile)
-```
-
-## Validate a proof
-
-```es6
-import { validateProofs } from 'blockstack'
-
-const domainName = "naval.id"
-validateProofs(profile, domainName).then((proofs) => {
-  console.log(proofs)
-})
-```
-
-## How proofs are validated
-
-The `validateProofs` function checks each of the proofs listed in the
-profile by fetching the proof URL and verifying the proof message. Currently supported proof validation services:
-
-- Facebook
-- Twitter
-- Instagram
-
-The proof message must be of the form:
-
-```
-Verifying my Blockstack ID is secured with the address
-1EeZtGNdFrVB2AgLFsZbyBCF7UTZcEWhHk
-```
-The proof message also must appear in the required location on the
-proof page specific to each type of social media account.
-
-The account from which the proof message is posted must match exactly
-the account identifier/username claimed in the user profile. The
-`validateProofs` function will check this in the body of the proof or
-in the proof URL depending on the service.
-
-## Adding additional social account validation services
-
-The `Service` class can be extended to provide proof validation service
-to additional social account types. You will need to override the
-`getProofStatement(searchText: string)` method which parses the proof
-body and returns the proof message text. Additionally, the identifier
-claimed should be verified in the proof URL or in the body by implementing
-`getProofIdentity(searchText: string)` and setting `shouldValidateIdentityInBody()`
-to return true.
-
-The following snippet uses the meta tags in the proof page to retrieve the proof message.
-```js
-static getProofStatement(searchText: string) {
-	const $ = cheerio.load(searchText)
-	const statement = $('meta[property="og:description"]')
-	                    .attr('content')
-
-	if (statement !== undefined && statement.split(':').length > 1) {
-	  return statement.split(':')[1].trim().replace('“', '').replace('”', '')
-	} else {
-	  return ''
-	}
-}
-```
+```