Tidy up documentation (2) (#2137)

* Tidy up documentation.

* Fix spelling (maybe)

* Fix CI

* Update docs/concepts/function-components.md

Co-authored-by: Muhammad Hamza <muhammadhamza1311@gmail.com>

* apply review

Co-authored-by: teymour-aldridge <teymour.aldridge@icloud.com>
Co-authored-by: Teymour Aldridge <42674621+teymour-aldridge@users.noreply.github.com>

ci/dictionary.txt

@@ -2,6 +2,7 @@ personal_ws-1.1 en 0 utf-8
 alloc
 ALLOC
 allocator
+analagous
 Angular's
 asmjs
 binaryen
@@ -13,6 +14,7 @@ cdylib
 charset
 codebase
 codegen
+Component
 composable
 Config
 declaratively
@@ -39,6 +41,7 @@ impl
 init
 INIT
 interop
+interoperate
 json
 lifecycle
 Lifecycle
@@ -78,5 +81,6 @@ Webpack
 WeeAlloc
 workspaces
 xmlns
+Javascript
 yewtil
 Yewtil

website/docs/concepts/agents.md

@@ -3,9 +3,16 @@ title: "Agents"
 description: "Yew's Actor System"
 ---
 
-Agents are similar to Angular's [Services](https://angular.io/guide/architecture-services) \(but without dependency injection\), and provide a Yew with an [Actor Model](https://en.wikipedia.org/wiki/Actor_model). Agents can be used to route messages between components independently of where they sit in the component hierarchy, or they can be used to create a shared state, and they can also be used to offload computationally expensive tasks from the main thread which renders the UI. There is also planned support for using agents to allow Yew applications to communicate across tabs \(in the future\).
+Agents are similar to Angular's [Services](https://angular.io/guide/architecture-services)
+\(but without dependency injection\), and provide Yew with an
+[Actor Model](https://en.wikipedia.org/wiki/Actor_model). Agents can be used to route messages
+between components independently of where they sit in the component hierarchy, or they can be used
+to create shared state between different components. Agents can also be used to offload
+computationally expensive tasks from the main thread which renders the UI. There is also planned
+support for using agents to allow Yew applications to communicate across tabs \(in the future\).
 
-In order for agents to run concurrently, Yew uses [web-workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers).
+In order for agents to run concurrently, Yew uses
+[web-workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers).
 
 ## Lifecycle
 
@@ -42,8 +49,13 @@ A dispatcher allows uni-directional communication between a component and an age
 
 ## Overhead
 
-Agents that live in their own separate web worker \(Private and Public\) incur serialization overhead on the messages they send and receive. They use [bincode](https://github.com/servo/bincode) to communicate with other threads, so the cost is substantially higher than just calling a function. Unless the cost of computation will outweigh the cost of message passing, you should contain your logic in the UI thread agents \(Job or Context\).
+Agents that use web workers \(i.e. Private and Public\) will incur a serialization overhead on the
+messages they send and receive. They use [bincode](https://github.com/servo/bincode) to communicate
+with other threads, so the cost is substantially higher than just calling a function. Unless the
+cost of computation will outweigh the cost of message passing, you should use agents running on the
+UI thread \(i.e. Job or Context\).
 
 ## Further reading
 
-* The [pub\_sub](https://github.com/yewstack/yew/tree/master/examples/pub_sub) example shows how components can use agents to communicate with each other.
+* The [pub\_sub](https://github.com/yewstack/yew/tree/master/examples/pub_sub) example shows how
+components can use agents to communicate with each other.

website/docs/concepts/function-components.md

@@ -4,11 +4,12 @@ sidebar_label: Introduction
 description: "Introduction to function components "
 ---
 
-Function components are a simplified version of normal components.
-They consist of a single function that receives props and determines what should be rendered by returning `Html`.
-Basically, it's a component that's been reduced to just the `view` method.
-On its own that would be quite limiting because you can only create pure components, but that's where Hooks come in.
-Hooks allow function components to use state and other Yew features without implementing the `Component` trait.
+Function components are a simplified version of normal components. They consist of a single function
+that receives props and determines what should be rendered by returning `Html`. Basically, it's a
+component that's been reduced to just the `view` method. On its own that would be quite limiting
+because you can only create pure components, but that's where Hooks come in. Hooks allow function
+components to maintain their own internal state and use other Yew features without needing to manually
+implement the `Component` trait.
 
 ## Creating function components
 
@@ -25,14 +26,19 @@ fn hello_world() -> Html {
 
 ### Under the hood
 
-Function components consists of two parts.
-First, the `FunctionProvider` trait which is comparable to the `Component` trait but it only has a single method called `run`.
-The second part is the `FunctionComponent` struct which wraps around the `FunctionProvider` type and turns it into an actual `Component`. 
-The `#[function_component]` attribute essentially just implements `FunctionProvider` for you and exposes it wrapped in `FunctionComponent`.
+There are two parts to how Yew implements function components.
+
+The first part is the `FunctionProvider` trait which is analogous to the `Component` trait, except
+that it only has a single method (called `run`). The second part is the `FunctionComponent` struct
+which wraps types implementing `FunctionProvider` and implements `Component`.
+
+The `#[function_component]` attribute is a procedural macro which automatically implements
+`FunctionProvider` for you and exposes it wrapped in `FunctionComponent`.
 
 ### Hooks
 
-Hooks are simply functions that let you “hook into” components' state and/or lifecycle and perform actions. Yew comes with a few pre-defined Hooks. You can also create your own.
+Hooks are functions that let you "hook into" components' state and/or lifecycle and perform
+actions. Yew comes with a few pre-defined Hooks. You can also create your own.
 
 #### Pre-defined Hooks
 
@@ -48,3 +54,8 @@ Yew comes with the following predefined Hooks:
 
 There are cases where you want to define your own Hooks for reasons. Yew allows you to define your own Hooks which lets you extract your potentially stateful logic from the component into reusable functions. 
 See the [Defining custom hooks](function-components/custom-hooks.md#defining-custom-hooks) section for more information.
+
+## Further reading
+
+* The React documentation has a section on [React hooks](https://reactjs.org/docs/hooks-intro.html).
+These are not exactly the same as Yew's hooks, but the underlying concept is similar.

website/docs/concepts/html/lists.md

@@ -4,7 +4,8 @@ title: "Lists"
 
 ## Fragments
 
-The `html!` macro always requires a single root node. In order to get around this restriction, it's valid to wrap content in empty tags:
+The `html!` macro always requires a single root node. In order to get around this restriction, you
+can use an "empty tag" (these are also called "fragments").
 
 <!--DOCUSAURUS_CODE_TABS-->
 <!--Valid-->
@@ -35,7 +36,10 @@ html! {
 
 ## Iterators
 
-Yew supports two different syntaxes for building html from an iterator:
+Yew supports two different syntaxes for building HTML from an iterator.
+
+The first is to call `collect::<Html>()` on the final transform in your iterator, which returns a
+list that Yew can display.
 
 <!--DOCUSAURUS_CODE_TABS-->
 <!--Syntax Type 1-->
@@ -51,6 +55,9 @@ html! {
 };
 ```
 
+The alternative is to use the `for` keyword, which is not native Rust syntax and instead is used by
+the HTML macro to output the needed code to display the iterator.
+
 <!--Syntax Type 2-->
 ```rust
 use yew::{html};
@@ -65,7 +72,7 @@ html! {
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
-## Relevant examples
+## Further reading
 - [TodoMVC](https://github.com/yewstack/yew/tree/master/examples/todomvc)
-- [Keyed List](https://github.com/yewstack/yew/tree/master/examples/keyed_list)
+- [Keyed list](https://github.com/yewstack/yew/tree/master/examples/keyed_list)
 - [Router](https://github.com/yewstack/yew/tree/master/examples/router)

website/versioned_docs/version-0.18.0/concepts/html.md

@@ -9,20 +9,32 @@ The `html!` macro allows you to write HTML and SVG code declaratively. It is sim
 
 **Important notes**
 
-1. The `html!` macro only accepts one root html node \(you can counteract this by
+1. The `html!` macro only accepts a single root HTML node \(this obstacle is easily overcome by
    [using fragments or iterators](html/lists.md)\)
 2. An empty `html! {}` invocation is valid and will not render anything
-3. Literals must always be quoted and wrapped in braces: `html! { "Hello, World" }`
+3. Literals must always be wrapped in quotes as well as braces (i.e.
+`html! { <p>{"Hello, World"}</p> }` is valid, but not `html! { <p>Hello, World</p> }` or
+`html! { <p>"Hello, World"</p> }`).
 
 :::note
-The `html!` macro can reach the default recursion limit of the compiler. If you encounter compilation errors, add an attribute like `#![recursion_limit="1024"]` in the crate root to overcome the problem.
+The requirement to need braces and quotes was not a deliberate design choice (just in case you're
+wondering)! It's needed in order to make parsing the tokens fed into the `html!` macro possible.
+:::
+
+:::note
+The `html!` macro can cause problems because it makes a lot of recursive calls. This means that it
+can exceed the default recursion limit of the compiler. If you encounter a compilation error
+(which might say something about "overflow" or "recursion limit reached") adding an attribute like
+`#![recursion_limit="1024"]` to your crate root should fix the problem.
 :::
 
 ## Tag Structure
 
-Tags are based on HTML tags. Components, Elements, and Lists are all based on this tag syntax.
+Tags inside the `html!` macros are heavily inspired by HTML tags. Components, elements, and lists
+all use the tag syntax.
 
-Tags must either self-close `<... />` or have a corresponding end tag for each start tag.
+Every tag must either either close itself (e.g. `<br/>`) or there must be a corresponding closing
+tag for each opening tag (e.g. `<div></div>`).
 
 <!--DOCUSAURUS_CODE_TABS-->
 <!--Open - Close-->
@@ -41,7 +53,7 @@ html! {
 use yew::html;
 
 html! {
-  <div id="my_div"> // <- MISSING CLOSE TAG
+  <div id="my_div"> // <- Missing closing tag
 }
 ```
 
@@ -61,19 +73,21 @@ html! {
 use yew::html;
 
 html! {
-  <input id="my_input"> // <- MISSING SELF-CLOSE
+  <input id="my_input"> // <- Missing forward slash to close the tag
 }
 ```
 
 <!--END_DOCUSAURUS_CODE_TABS-->
 
 :::tip
-For convenience, elements which _usually_ require a closing tag are **allowed** to self-close. For example, writing `html! { <div class="placeholder" /> }` is valid.
+For convenience, elements which _usually_ require a closing tag can be declared using the
+self-closing syntax (e.g. `html! { <div class="placeholder" /> }` is valid).
 :::
 
 ## Children
 
-Create complex nested HTML and SVG layouts with ease:
+Tags become much more powerful once we start to nest them. Tags may have children (which can be
+other standard HTML tags or other Yew components).
 
 <!--DOCUSAURUS_CODE_TABS-->
 <!--HTML-->
@@ -127,15 +141,26 @@ html! {
 
 ## Special properties
 
-There are special properties which don't directly influence the DOM but instead act as instructions to Yew's virtual DOM.
+Some properties aren't handed directly to the browser; instead Yew uses them when working out how to
+display your components.
+
 Currently, there are two such special props: `ref` and `key`.
 
-`ref` allows you to access and manipulate the underlying DOM node directly. See [Refs](components/refs) for more details.
+`ref` allows you to access and manipulate the underlying DOM node directly. See
+[Refs](components/refs) for more details. This can be very useful if you want to interoperate with
+Javascript libraries (for example, to add a map or code editor written in Javascript that would not
+be feasible to rewrite in Rust).
 
-`key` on the other hand gives an element a unique identifier which Yew can use for optimization purposes.
+`key` on the other hand gives an element in a list a unique identifier which Yew can use for
+to render lists more efficiently.
 
 :::important
 The documentation for keys is yet to be written. See [#1263](https://github.com/yewstack/yew/issues/1263).
 
-For now, use keys when you have a list where the order of elements changes. This includes inserting or removing elements from anywhere but the end of the list.
+For now, use keys when you have a list where the order of elements might change. This includes
+inserting or removing elements from anywhere but the end of the list.
 :::
+
+## Relevant examples
+* The [NodeRef example](https://github.com/yewstack/yew/tree/master/examples/node_refs)
+* An example of [using NodeRefs to integrate a code editor into an application](https://github.com/siku2/rust-monaco/blob/master/src/yew/mod.rs)

website/versioned_docs/version-0.18.0/concepts/html/literals-and-expressions.md

@@ -3,10 +3,11 @@ title: "Literals and Expressions"
 ---
 ## Literals
 
-If expressions resolve to types that implement `Display`, they will be converted to strings and inserted into the DOM as a [Text](https://developer.mozilla.org/en-US/docs/Web/API/Text) node.
+If expressions resolve to types that implement `Display`, they will be converted to strings and
+inserted into the DOM as a [Text](https://developer.mozilla.org/en-US/docs/Web/API/Text) node.
 
-All display text must be enclosed by `{}` blocks because text is handled as an expression. This is 
-the largest deviation from normal HTML syntax that Yew makes.
+All display text must be enclosed by `{}` blocks because the `html!` macro parses text as a Rust
+expression. This is the greatest deviation from the HTML specification that the `html!` macro makes.
 
 ```rust
 use yew::html;
@@ -43,7 +44,9 @@ html! {
 }
 ```
 
-It often makes sense to extract these expressions into functions or closures to optimize for readability:
+It often makes sense to extract these expressions into separate functions or closures to make your
+code more readable. This can also help to reduce code duplication by moving common elements of your
+UI into composable functions.
 
 ```rust
 use yew::{html, Html};