From bacf2bf0324814fe9d5f414e92443a889c90b6ea Mon Sep 17 00:00:00 2001
From: Mark Hendrickson <markhendrickson@Mac-mini.local>
Date: Mon, 11 Jan 2021 17:36:43 +0100
Subject: [PATCH] feat: address feedback from PR #1014

---
 next.config.js                                | 33 ++++++++++++++-----
 src/pages/404.md                              | 25 +++++++++++---
 src/pages/build-apps/guides/authentication.md | 23 +++++++++----
 src/pages/build-apps/guides/data-storage.md   | 11 +++----
 .../build-apps/guides/transaction-signing.md  | 26 +++++++--------
 src/pages/build-apps/indexing/overview.md     |  7 ++--
 src/pages/build-apps/overview.md              | 10 +++---
 src/pages/build-apps/tutorials/angular.md     |  4 +--
 src/pages/build-apps/tutorials/indexing.md    |  2 +-
 src/pages/build-apps/tutorials/todos.md       |  2 +-
 src/pages/understand-stacks/atlas-overview.md |  2 +-
 src/pages/understand-stacks/overview.md       |  2 +-
 12 files changed, 92 insertions(+), 55 deletions(-)

diff --git a/next.config.js b/next.config.js
index 09b6d9d8..8a5083b7 100755
--- a/next.config.js
+++ b/next.config.js
@@ -51,12 +51,17 @@ async function redirects() {
     },
     {
       source: '/develop/storage.html',
-      destination: '/build-apps/references/gaia',
+      destination: '/build-apps/guides/data-storage',
       permanent: true,
     },
     {
-      source: '/data-storage/overview',
-      destination: '/build-apps/references/gaia',
+      source: '/data-storage/storage-write-read',
+      destination: '/build-apps/guides/data-storage',
+      permanent: true,
+    },
+    {
+      source: '/data-storage/storage-guide',
+      destination: '/build-apps/guides/data-storage',
       permanent: true,
     },
     {
@@ -64,6 +69,11 @@ async function redirects() {
       destination: '/build-apps/references/gaia',
       permanent: true,
     },
+    {
+      source: '/data-storage/authentication',
+      destination: '/build-apps/guides/authentication',
+      permanent: true,
+    },
     {
       source: '/storage/authentication.html',
       destination: '/data-storage/authentication',
@@ -126,7 +136,7 @@ async function redirects() {
     },
     {
       source: '/develop/connect/use-with-clarity.html',
-      destination: '/build-apps/transaction-signing',
+      destination: '/build-apps/guides/transaction-signing',
       permanent: true,
     },
     {
@@ -234,6 +244,11 @@ async function redirects() {
       destination: '/build-apps/collections/types',
       permanent: true,
     },
+    {
+      source: '/data-storage/collection-type',
+      destination: '/build-apps/collections/types',
+      permanent: true,
+    },
     {
       source: '/data-storage/collections-type',
       destination: '/build-apps/collections/types',
@@ -707,12 +722,12 @@ async function redirects() {
     },
     {
       source: '/smart-contracts/signing-transactions',
-      destination: '/build-apps/transaction-signing',
+      destination: '/build-apps/guides/transaction-signing',
       permanent: true,
     },
     {
       source: '/write-smart-contracts/signing-transactions',
-      destination: '/build-apps/transaction-signing',
+      destination: '/build-apps/guides/transaction-signing',
       permanent: true,
     },
     {
@@ -822,17 +837,17 @@ async function redirects() {
     },
     {
       source: '/smart-contracts/public-registry-tutorial',
-      destination: '/build-apps/tutorial/public-registry',
+      destination: '/build-apps/tutorials/public-registry',
       permanent: true,
     },
     {
       source: '/smart-contracts/public-registry-tutorial',
-      destination: '/build-apps/tutorial/public-registry',
+      destination: '/build-apps/tutorials/public-registry',
       permanent: true,
     },
     {
       source: '/write-smart-contracts/public-registry-tutorial',
-      destination: '/build-apps/tutorial/public-registry',
+      destination: '/build-apps/tutorials/public-registry',
       permanent: true,
     },
     {
diff --git a/src/pages/404.md b/src/pages/404.md
index ba14925c..1ded2223 100644
--- a/src/pages/404.md
+++ b/src/pages/404.md
@@ -5,14 +5,29 @@ description: The page you're looking for isn't here.
 
 ## Whoops
 
-Looks like the page you are looking for isn't here. [Head back home](/) or try out some of these popular pages:
+Looks like the page you are looking for isn't here. Try out some of these popular pages:
 
-## Tutorials
+## Understand Stacks
 
 [@page-reference | grid]
-| /authentication/building-todo-app, /write-smart-contracts/counter-tutorial
+| /understand-stacks/overview, /understand-stacks/proof-of-transfer, /understand-stacks/testnet
 
-## Explore
+## Write smart contracts
+
+[@page-reference | grid]
+| /write-smart-contracts/overview, /write-smart-contracts/hello-world-tutorial
+
+## Build apps
+
+[@page-reference | grid]
+| /build-apps/guides/authentication, /build-apps/guides/transaction-signing, /build-apps/guides/data-storage
+
+## Start mining
+
+[@page-reference | grid]
+| /start-mining, /understand-stacks/running-testnet-node
+
+## Ecosystem
 
 [@page-reference | grid-small]
-| /ecosystem/overview, /ecosystem/stacks-token, /understand-stacks/testnet-node
+| /ecosystem/overview, /ecosystem/stacks-token, /ecosystem/contributing
diff --git a/src/pages/build-apps/guides/authentication.md b/src/pages/build-apps/guides/authentication.md
index bb565645..670a7771 100644
--- a/src/pages/build-apps/guides/authentication.md
+++ b/src/pages/build-apps/guides/authentication.md
@@ -1,9 +1,6 @@
 ---
 title: Authentication
 description: Register and sign in users with identities on the Stacks blockchain
-experience: beginners
-tags:
-  - tutorial
 images:
   large: /images/pages/write-smart-contracts.svg
   sm: /images/pages/write-smart-contracts-sm.svg
@@ -17,7 +14,10 @@ Authentication provides a way for users to identify themselves to an app while r
 
 Users who register for your app can subsequently authenticate to any other app with support for the [Blockchain Naming System](/build-apps/references/bns) and vice versa.
 
-[See the Todos app tutorial](/build-apps/tutorials/todos) for a concrete example of this functionality in practice.
+See the Todos app tutorial for a concrete example of this functionality in practice.
+
+[@page-reference]
+| /build-apps/tutorials/todos
 
 ## How it works
 
@@ -154,9 +154,20 @@ It will then trigger the `finished` function provided above, which can be used s
 
 ## Usage in React Apps
 
-Import the `useConnect` from the `connect` package to integrate transaction signing more seamlessly into React apps.
+Import the `useConnect` from the [`connect-react`](https://github.com/blockstack/ux/tree/master/packages/connect-react) package to integrate authentication more seamlessly into React apps.
+
+```
+npm install @stacks/connect-react
+```
+
+```jsx
+import { useConnect } from '@stacks/connect-react';
 
-TODO: Add guidance for authentication with React
+const AuthButton = () => {
+  const { doOpenAuth } = useConnect();
+  return <Button onClick={() => doOpenAuth()}>Authenticate</Button>;
+};
+```
 
 ## Key pairs
 
diff --git a/src/pages/build-apps/guides/data-storage.md b/src/pages/build-apps/guides/data-storage.md
index f002cd32..f73efe5f 100644
--- a/src/pages/build-apps/guides/data-storage.md
+++ b/src/pages/build-apps/guides/data-storage.md
@@ -1,9 +1,6 @@
 ---
 title: Data storage
 description: Save and retrieve data for users with Gaia
-experience: beginners
-tags:
-  - tutorial
 images:
   large: /images/gears.svg
   sm: /images/gears.svg
@@ -17,15 +14,17 @@ Data storage provides a way for users to save both public and private data off-c
 
 Storing data off the Stacks blockchain ensures that apps can provide users with high performance and high availability for data reads and writes without the involvement of centralized parties that could compromise their privacy or accessibility.
 
-[See the Todos app tutorial](/build-apps/tutorials/todos) for a concrete example of this functionality in practice.
+See the Todos app tutorial](/build-apps/tutorials/todos for a concrete example of this functionality in practice.
+
+[@page-reference]
+| /build-apps/tutorials/todos
 
 ## Install dependencies
 
 The following dependencies must be installed:
 
 ```
-npm install @stacks/connect
-npm install @stacks/storage
+npm install @stacks/connect @stacks/storage
 ```
 
 ## Initiate session
diff --git a/src/pages/build-apps/guides/transaction-signing.md b/src/pages/build-apps/guides/transaction-signing.md
index a7206b58..546c00b0 100644
--- a/src/pages/build-apps/guides/transaction-signing.md
+++ b/src/pages/build-apps/guides/transaction-signing.md
@@ -1,9 +1,6 @@
 ---
 title: Transaction signing
 description: Prompt users to sign and broadcast transactions to the Stacks blockchain
-experience: beginners
-tags:
-  - tutorial
 images:
   large: /images/transaction-signing.svg
   sm: /images/transaction-signing.svg
@@ -11,9 +8,9 @@ images:
 
 ## Introduction
 
-This guide explains how to prompt users to sign [transactions](/understand-stacks/transactions) and broadcast them to the Stacks blockchain by implementing the `connect` package of [Stacks.js](https://blockstack.github.io/stacks.js/).
+This guide explains how to prompt users to sign [transactions](/understand-stacks/transactions) and broadcast them to the Stacks blockchain by implementing the [`connect`](https://github.com/blockstack/ux/tree/master/packages/connect#stacksconnect) package of Stacks.js.
 
-Transaction signing provides a way for users execute [Clarity smart contracts](/write-smart-contracts/overview) that are relevant to your app then handle the result immediately.
+Transaction signing provides a way for users execute [Clarity smart contracts](/write-smart-contracts/overview) that are relevant to your app then handle the result as appropriate.
 
 Users can sign transactions that exchange fungible or non-fungible tokens with upfront guarantees that help them retain control over their digital assets.
 
@@ -23,7 +20,10 @@ There are three types of transactions:
 2. Contract deployment
 3. Contract execution
 
-[See the public registry tutorial](/build-apps/tutorials/public-registry) for a concrete example of this functionality in practice.
+See the public registry tutorial for a concrete example of this functionality in practice.
+
+[@page-reference]
+| /build-apps/tutorials/public-registry
 
 ## Install dependency
 
@@ -195,7 +195,7 @@ interface ContractCallOptions {
 
 ### Passing Clarity types with function arguments
 
-To serialize your transaction properly, you'll need to provide an appropriate Clarity type for each function argument.
+To serialize your transaction properly, you'll need to provide an appropriate [Clarity type](/references/language-types) for each function argument.
 
 These types are named the same as in Clarity and must be passed as strings:
 
@@ -224,7 +224,11 @@ const functionArguments = [
 
 ## Usage in React Apps
 
-Import the `useConnect` from the `connect` package to integrate transaction signing more seamlessly into React apps.
+Import the `useConnect` from the [`connect-react`](https://github.com/blockstack/ux/tree/master/packages/connect-react) package to integrate transaction signing more seamlessly into React apps.
+
+```
+npm install @stacks/connect-react
+```
 
 Each transaction signing method is itself available as a function returned by `useConnect` though prefixed with `do` for consistency with React action naming standards:
 
@@ -235,7 +239,7 @@ Each transaction signing method is itself available as a function returned by `u
 Use these functions with the same parameters as outlined above. However, you don't have to specify `appDetails` since they are detected automatically if `useConnect` has been used already for authentication.
 
 ```tsx
-import { useConnect } from '@stacks/connect';
+import { useConnect } from '@stacks/connect-react';
 
 const MyComponent = () => {
   const { doContractCall } = useConnect();
@@ -251,10 +255,6 @@ const MyComponent = () => {
 };
 ```
 
-## Change network
-
-TBD: Instructions for changing between mainnet, testnet and local networks
-
 ## Request testnet STX from faucet
 
 You may find it useful to request testnet STX from [the faucet](https://testnet.blockstack.org/faucet) while developing your app with the Stacks testnet.
diff --git a/src/pages/build-apps/indexing/overview.md b/src/pages/build-apps/indexing/overview.md
index 4bf26b7b..6eb241ee 100644
--- a/src/pages/build-apps/indexing/overview.md
+++ b/src/pages/build-apps/indexing/overview.md
@@ -17,10 +17,7 @@ multi-player DApps that:
 - display real-time updates that reflect in progress changes
 - support collaboration among sets of users
 
-Want to jump right in and start integrating indexing into your app? Try this tutorial:
-
-[@page-reference | inline]
-| /data-storage/integrate-indexing
+Want to jump right in and start integrating indexing into your app? [Try this tutorial](/build-apps/tutorials/indexing).
 
 ## Why use Radiks?
 
@@ -93,4 +90,4 @@ All data is also stored in Gaia; no third-party can revoke access to this data.
 All data is encrypted on the client-side before being stored anywhere using Stacks authorization. The application
 host cannot inspect, sell, or use user data in any way that a user doesn't explicitly authorize.
 
-If you are not familiar with Gaia, see [read the Gaia documentation](/data-storage/overview).
+If you are not familiar with Gaia, see [read the Gaia documentation](/build-apps/references/gaia).
diff --git a/src/pages/build-apps/overview.md b/src/pages/build-apps/overview.md
index 3225b070..c96222b6 100644
--- a/src/pages/build-apps/overview.md
+++ b/src/pages/build-apps/overview.md
@@ -10,17 +10,17 @@ images:
 
 Apps built with the Stacks blockchain give users control over their digital identities, assets and data.
 
-Unlike most cloud-based apps, they are "decentralized" since they don't depend on any centralized platform, server or database to function. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write transactions for them without any single point of failure or trust.
+Unlike most cloud-based apps, they are "decentralized" since they don't depend on any centralized platform, server or database to function. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust.
 
 This page provides information on how to build such apps using [Stacks.js](https://github.com/blockstack/stacks.js) and other libraries that make integration of the Stacks blockchain easy for front-end developers.
 
-Three main types of integration are available:
+Three main integrations are available:
 
-- **Authentication**: Register and sign in users with identities with the Stacks blockchain
+- **Authentication**: Register and sign users in with identities on the Stacks blockchain
 - **Transaction signing**: Prompt users to sign and broadcast transactions to the Stacks blockchain
-- **Data storage**: Save and retrieve data for users with Gaia
+- **Data storage**: Save and retrieve data for users with [Gaia](/build-apps/references/gaia)
 
-All three of these types can be used together to create powerful new user experiences that rival or exceed those of traditional apps – all while protecting your users' digital rights.
+All three of these integrations can be used together to create powerful new user experiences that rival or exceed those of traditional apps – all while protecting your users' digital rights.
 
 While integration is possible for any type of app, most of the resources available here are for web developers experienced with JavaScript.
 
diff --git a/src/pages/build-apps/tutorials/angular.md b/src/pages/build-apps/tutorials/angular.md
index 79d5a02f..f45c7532 100644
--- a/src/pages/build-apps/tutorials/angular.md
+++ b/src/pages/build-apps/tutorials/angular.md
@@ -14,7 +14,7 @@ images:
 
 ## Getting started with Angular
 
-In this tutorial, you'll learn how to work with Stacks Connect when using [Angular](https://angular.io/) as your framework of choice. It builds on what you've learnt in the [Authentication Overview](/authentication/overview).
+In this tutorial, you'll learn how to work with Stacks Connect when using [Angular](https://angular.io/) as your framework of choice. It builds on what you've learnt in the [Authentication Overview](/build-apps/guides/authentication).
 
 -> This article presumes some familiarity with [Angular](https://angular.io/), as well as [Reactive Extensions (RxJS)](https://rxjs.dev/).
 
@@ -122,7 +122,7 @@ Here we're using an Rxjs `Subject` to represent a stream of sign in events. `sta
 
 ### 4.3 Authentication
 
-First, describe the auth options we need to pass to Connect. [Learn more about `AuthOptions` here](/authentication/overview). Let's modify the default component to look like this:
+First, describe the auth options we need to pass to Connect. [Learn more about `AuthOptions` here](/build-apps/guides/authentication). Let's modify the default component to look like this:
 
 ```typescript
 import { Component } from '@angular/core';
diff --git a/src/pages/build-apps/tutorials/indexing.md b/src/pages/build-apps/tutorials/indexing.md
index e5278995..a4184edc 100644
--- a/src/pages/build-apps/tutorials/indexing.md
+++ b/src/pages/build-apps/tutorials/indexing.md
@@ -224,4 +224,4 @@ The `maxLimit` option is the maximum `limit` field used inside the mongo queries
 
 ## Where to go next
 
-Creating models for your application's data is where radiks truly becomes helpful. To learn how to use models, see the [Create and use models](/data-storage/indexing-models) section.
+Creating models for your application's data is where radiks truly becomes helpful. To learn how to use models, see the [Create and use models](/build-apps/indexing/models) section.
diff --git a/src/pages/build-apps/tutorials/todos.md b/src/pages/build-apps/tutorials/todos.md
index 1db9980d..cc054a1b 100644
--- a/src/pages/build-apps/tutorials/todos.md
+++ b/src/pages/build-apps/tutorials/todos.md
@@ -116,7 +116,7 @@ The `showConnect` function accepts a number of properties within a parameter obj
 
 - The app's `name` and `icon`: provided as strings comprising the `appDetails` object property.
 - The `redirectTo` string: used to provide a URL to which the user should be redirected upon successful authentication. The `finished` callback serves a similar purpose by handling successful authentication within a context of a popup window.
-- The `userSession` object: used to pass the [scopes](/authentication/overview#scopes) needed by the app.
+- The `userSession` object: used to pass the [scopes](/build-apps/guides/authentication#initiate-usersession-object) needed by the app.
 
 Note how the `userSession` object is created at the beginning of this module by leveraging an `AppConfig` object that's first initiated with all relevant scopes.
 
diff --git a/src/pages/understand-stacks/atlas-overview.md b/src/pages/understand-stacks/atlas-overview.md
index 7371991f..5bef82c0 100644
--- a/src/pages/understand-stacks/atlas-overview.md
+++ b/src/pages/understand-stacks/atlas-overview.md
@@ -13,7 +13,7 @@ all chunks are available to clients.
 
 This document is aimed at developers and technical users.
 
-The reader of this document is expected to be familiar with the [Blockchain Naming Service](/technology/naming-system/)(BNS),
+The reader of this document is expected to be familiar with the [Blockchain Naming Service (BNS)](/build-apps/references/bns),
 as well as Stacks's storage system [Gaia](https://github.com/blockstack/gaia). We advise the reader
 to familiarize themselves with both systems before approaching this document.
 
diff --git a/src/pages/understand-stacks/overview.md b/src/pages/understand-stacks/overview.md
index 8f07dbf2..dd99a436 100644
--- a/src/pages/understand-stacks/overview.md
+++ b/src/pages/understand-stacks/overview.md
@@ -82,7 +82,7 @@ Clarity is distinct from other languages designed for writing smart contracts in
 Stacks 2.0 enabled building decentralized apps that are user-owned and avoid centralized servers.
 
 [@page-reference | inline]
-| /build-apps
+| /build-apps/overview, /build-apps/guides/authentication, /build-apps/guides/transaction-signing, /build-apps/guides/data-storage
 
 ## Guides