Merge pull request #1258 from square/ray/nav

Typos, broken links, fussing with top level org.

Author: rjrjr

docs/userguide/concepts.md

@@ -1,4 +1,7 @@
-# Core Concepts
+# Workflow Core Concepts
+
+This page provides a high level overview of Workflow Core, the UI-agnostic Swift and Kotlin runtimes at the heart of the Workflow libraries.
+See [Workflow UI Concepts](../ui-concepts) to learn about the companion Android and iOS specific modules.
 
 ## What is a Workflow?
 
@@ -18,8 +21,8 @@ For example, a Workflow running a simple game might be configured with a descrip
 ![Workflow schematic with State type GameState, Props type Players, Rendering type GameScreen, and Output type GameOver. The workflow is receiving an onClick() event.](../images/game_workflow_schematic.svg)
 
 A workflow Rendering usually serves as a view model in iOS or Android apps, but that is not a requirement.
-In fact, this page includes no details about how platform specific UI code is driven.
-See [Workflow UI](../ui-concepts) for that discussion.
+Again, this page includes no details about how platform specific UI code is driven.
+See [Workflow UI Concepts](../ui-concepts) for that discussion.
 
 !!! note
      Readers with an Android background should note the lower case _v_ and _m_ of "view model" — this notion has nothing to do with Jetpack `ViewModel`.
@@ -85,9 +88,9 @@ WIP
 
 ## Why does Workflow work this way?
 
-Worklow was built to tame the composition and navigation challenges presented by Square's massive Android and iOS apps.
+Workflow was built to tame the composition and navigation challenges presented by Square's massive Android and iOS apps.
 It lets us write intricate, centralized, well tested code encapsulating the flow through literally hundreds of individual screens.
-We are no longer unable to see the forest for the trees.
+These days we are able to see and shape the forest, despite all of the trees.
 
 We built it with two core design principals in mind:
 

docs/userguide/ui-concepts.md

@@ -1,6 +1,6 @@
-# Workflow UI
+# Workflow UI Concepts
 
-This page provides a high level overview of Workflow UI, the companion that allows [Workflow Core](../core-workflow) to drive Android and iOS apps.
+This page provides a high level overview of Workflow UI, the companion that allows [Workflow Core](../concepts) to drive Android and iOS apps.
 
 !!! warning Kotlin WIP
     The `Screen` interface that is so central to this discussion has reached Kotlin very recently, via `v1.8.0-beta01`.
@@ -12,7 +12,7 @@ This page provides a high level overview of Workflow UI, the companion that allo
 ## Separation of Concerns
 
 Workflow maintains a rigid separation between its core runtime and its UI support.
-The [Workflow Core](../core-workflow) modules are strictly Swift and Kotlin, with no dependencies on any UI framework.
+The [Workflow Core](../concepts) modules are strictly Swift and Kotlin, with no dependencies on any UI framework.
 Dependencies on Android and iOS are restricted to the Workflow UI modules, as you would expect.
 This innate separation naturally puts developers on a path to avoid entangling view concerns with their app logic.
 
@@ -26,7 +26,7 @@ The strict divide between Workflow UI and Workflow Core leads you to maintain th
 
 ## What's a Screen?
 
-Most Workflow implementations produce `struct` / `data class` [renderings](../core-workflow#rendering) that can serve as view models.
+Most Workflow implementations produce `struct` / `data class` [renderings](../../glossary#rendering) that can serve as view models.
 Such a rendering provides enough data to paint a UI, and functions to be called in response to UI events.
 
 These view model renderings implement the `Screen` [protocol](https://github.com/square/workflow-swift/blob/main/WorkflowUI/Sources/Screen/Screen.swift) / [interface](https://github.com/square/workflow-kotlin/blob/main/workflow-ui/core-common/src/main/java/com/squareup/workflow1/ui/Screen.kt) to advertise that this is their intended use.

mkdocs.yml

@@ -89,10 +89,10 @@ nav:
   - 'Why Workflow?': 'userguide/whyworkflow.md'
   - 'User Guide':
     - 'Core Concepts': 'userguide/concepts.md'
+    - 'UI Concepts (in progress)': 'userguide/ui-concepts.md'
     - 'Coding a Workflow': 'userguide/workflow-in-code.md'
     - 'Coding a Worker': 'userguide/worker-in-code.md'
     - 'Testing (TBD)': 'userguide/testing-concepts.md'
-    - 'Workflow UI (in progress)': 'userguide/ui-concepts.md'
     - 'Common Patterns': 'userguide/common-patterns.md'
     - 'Implementation Notes': 'userguide/implementation.md'
   - 'Tutorials and Samples':