General docs cleanup

CHANGELOG.md

@@ -18,7 +18,7 @@ A complete rewrite.
 - Components track attributes they add and will only overwrite existing attribute values where required (#73)
 - Components are now exported from their own endpoint (#84)
 - MenuBar and MenuButton components are now deprecated (#75)
-- Component state now uses setter/getter pattern (#83)
+- Component state now uses a setter/getter pattern (#83)
 
 **Changed**
 

src/Dialog/README.md

@@ -1,7 +1,8 @@
 Dialog
 ======
 
-Class for managing an interactive Dialog element.
+Class for managing an interactive Dialog element, typically overlaid on inert 
+content, that traps focus and prevents interaction with the outside content.
 
 ## Contents
 
@@ -157,7 +158,7 @@ Additionally, the close button may not be the most appropriate element to focus
 
 > When a dialog opens, focus moves to an element contained in the dialog. Generally, focus is initially set on the first focusable element. However, the most appropriate focus placement will depend on the nature and size of the content.
 
-If the close button is not the most appropriate element to focus when the Dialog opens, we can omit the `closeButton` option to prevent the Dialog from managing focus. We can then manage focus and the close button ourselves.
+If the close button is not the most appropriate element to focus when the Dialog opens, omit the `closeButton` option to prevent the Dialog from managing focus and manage focus and the close button manually.
 
 ```jsx
 // Set up the close button.
@@ -174,7 +175,7 @@ dialog.on('dialog.stateChange', (event) => {
 
 **DOM Mutations**
 
-We can use `dialog.setInteractiveChildren()` to refresh the component after markup changes.
+Use `dialog.setInteractiveChildren()` to refresh the component after markup changes.
 
 ## References
 

src/Disclosure/README.md

@@ -104,7 +104,7 @@ Hides the target element with the `hidden` attribute, removing the need to do it
 
 ## Additional Information
 
-The `loadOpen` option is removed, in part because it's possible to achieve the same result without the option: Add `aria-expanded="true"` to the controling element and `aria-hidden="false"` to the target element and the attribute will treat it as expanded by default.
+Previously, there existsed a `loadOpen` option for initializing a Disclosure in the expanded state. To achieve the same result: Add `aria-expanded="true"` to the controling element and `aria-hidden="false"` to the target element.
 
 ## References
 

src/Listbox/README.md

@@ -1,7 +1,8 @@
 Listbox
 =======
 
-Class for setting up an interactive Listbox element.
+Class for setting up an interactive single-select Listbox for presenting a list 
+of options and allowing a user to select one of them.
 
 ## Contents
 

src/Popup/README.md

@@ -1,7 +1,8 @@
 Popup
 =====
 
-Class for setting up an interactive popup button to activate a target element.
+Class for setting up an interactive popup button to activate a target element 
+for displaying hidden content.
 
 ## Example
 

src/Tablist/README.md

@@ -151,7 +151,7 @@ Authors are responsible for providing a label for the Tablist. See ["Role, Prope
 
 > If the tab list has a visible label, the element with role tablist has aria-labelledby set to a value that refers to the labelling element. Otherwise, the tablist element has a label provided by aria-label.
 
-The recommendation is to only auto-active tabs as they're selected if the associated panel's content [isn't preloaded](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/). Otherwise, we can use the `AutomaticActivation` module:
+The recommendation is to only auto-active tabs as they're selected if the associated panel's content [isn't preloaded](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/). Otherwise, use the `AutomaticActivation` module:
 
 ```jsx
 import Tablist, { AutomaticActivation } from 'aria-components/tablist';

src/shared/modules/README.md

@@ -55,7 +55,7 @@ export default function DoSomethingHelpful({ instance }) {
 }
 ```
 
-The following properties are passed to modules:
+An object with the following properties is passed to modules:
 
 | Property    | Type          | Description                           |
 |:------------|:-------------:|:--------------------------------------|