docs: ✏️ simple edits during review of design docs (#255)

# Description

Did a small review and make a few minor fixes.

Needs a quick review.

## Checklist

- [x] Formatted Markdown
- [x] Ran `just run-all`

---------

Co-authored-by: martonvago <57952344+martonvago@users.noreply.github.com>

Author: lwjohnst86

docs/design/architecture.qmd

@@ -8,7 +8,7 @@ whole, see the [Seedcase Design](https://design.seedcase-project.org)
 documentation.
 
 This document outlines the architecture of `check-datapackage` mostly to
-ensure the team shares a common understanding before implementation, but
+ensure the team shares a common understanding about the implementation, but
 also to communicate the design to anyone else interested in the internal
 workings of the package.
 
@@ -57,7 +57,7 @@ used throughout the package can be found in the tables below.
 
 : Actions that `check-datapackage` can perform.
 
-### "Why "check" (and not "validate" or "verify")?
+### Why "check" and not "validate" or "verify"?
 
 If you have ever searched for tools that check something against a
 specification, you'll often see the word "validate". You might also
@@ -197,14 +197,15 @@ do not include a component/code diagram for it at this time.
 ```{mermaid}
 %%| label: fig-c4-component
 %%| fig-cap: "C4 component diagram showing the parts of the Python package and their connections."
+%%| column: page-right
 flowchart LR
 
     subgraph python_package["Core Python Package"]
 
         subgraph config_file["Configuration file"]
             config("Config<br>[class]")
             exclusion("Exclusion<br>[class]")
-            extension("Extension<br>[class]")
+            extension("Extensions<br>[class]")
         end
 
         read_config["read_config()<br>[function]"]
@@ -216,11 +217,11 @@ flowchart LR
         extension --"Defines additional checks"--> config
         config_file -. "Reads configuration<br>from file" .-> read_config
 
-        read_json --"Provides properties as dict"--> check
+        read_json --"Provides properties<br>as dict"--> check
         read_config -. "Adds check<br>configurations" .-> check
         config --"Adds check<br>configurations"--> check
 
-        check --"Passes found issues<br>to get non-technical<br>explanation"--> explain
+        check --"Passes issues to<br>give more helpful<br>explanation"--> explain
     end
 
     dp_standard("Data Package<br>[standard]")

docs/design/index.qmd

@@ -6,7 +6,7 @@ The purpose of these design documents is to describe the design of
 `check-datapackage` in enough detail to guide a sustainable
 implementation (i.e., maintainable in the long term) and to ensure that
 the team has a shared understanding of the package's scope and
-architecture before starting the development.
+architecture.
 
 `check-datapackage`'s design builds off of our overall Seedcase [design
 principles and patterns](https://design.seedcase-project.org/), and

docs/design/interface.qmd

@@ -5,7 +5,6 @@ title: "Interface"
 This section of the documentation focuses on the design of the interface
 and how it is implemented as Python code.
 
-::: callout-note
 We use symbols to indicate parts of the design that are actively being
 worked on, done, or planned (see table below). For work that is planned
 or is in progress, we include the function signatures and docstrings to
@@ -22,7 +21,6 @@ below.
 
 : A table showing the symbols used to indicate the status of interface
 components, along with their descriptions.
-:::
 
 ## Inputs
 
@@ -60,13 +58,14 @@ CLI or if it could be used some way as Python code. I didn't include it
 for now though.
 :::
 
-### {{< var wip >}} `check()`
+### {{< var done >}} `check()`
 
 This is the main function of this package, which will check a Data
 Package properties against the Data Package standard, as well as include
 any custom exclusions or custom checks listed in the configuration.
 
-See the help documentation with `help(check)` for more details.
+See the help documentation with
+[`help(check)`](/docs/reference/check.qmd) for more details.
 
 The `Config` class is described below. By default, `check()` does not
 result in an error when issues are found, but errors can be triggered by
@@ -84,19 +83,8 @@ user-friendly. It's important to have this output to provide structured
 information about the issues, but we also want to provide a way to
 explain these issues in a more pleasant and ergonomic way.
 
-``` python
-def explain(issues: list[Issue]) -> list[str]:
-    """Explain a list of issues in a user-friendly way.
-
-    Args:
-        issues: A list of `Issue` objects representing issues found while
-            checking a Data Package properties.
-
-    Returns:
-        A list of user-friendly, human-readable messages
-            explaining each issue.
-    """
-```
+See the help documentation with
+[`help(explain)`](/docs/reference/explain.qmd) for more details.
 
 ### {{< var done >}} `read_json()`
 
@@ -134,15 +122,17 @@ be useful for a CLI interface.
 `Config` is a class that holds all the configurations for the `check()`
 function.
 
-See the help documentation with `help(Config)` for more details.
+See the help documentation with
+[`help(Config)`](/docs/reference/Config.qmd) for more details.
 
 ### {{< var done >}} `Exclusion`
 
 A sub-item of `Config` that expresses checks to exclude. This can be
 useful if you want to exclude (or skip) certain checks from the Data
 Package standard that are not relevant to your use case.
 
-See the help documentation with `help(Exclusion)` for more details.
+See the help documentation with
+[`help(Exclusion)`](/docs/reference/Exclusion.qmd) for more details.
 
 #### {{< var done >}} `Extensions`
 
@@ -156,14 +146,16 @@ See the help documentation with
 
 A sub-item of `Extensions` that allows users to set specific properties
 as required that are not required by the Data Package standard. See the
-help documentation with `help(RequiredCheck)` for more details.
+help documentation with
+[`help(RequiredCheck)`](/docs/reference/RequiredCheck.qmd) for more
+details.
 
 #### {{< var done >}} `CustomCheck`
 
 A sub-item of `Extensions` that allows users to add an additional,
 custom check that `check-datapackage` will run alongside the standard
-checks. See the help documentation with `help(CustomCheck)` for more
-details.
+checks. See the help documentation with
+[`help(CustomCheck)`](/docs/reference/CustomCheck.qmd) for more details.
 
 ### {{< var done >}} `Issue`
 
@@ -216,11 +208,12 @@ check = "lambda name: name.islower()"
 
 ## Flow
 
-This is the potential flow of using `check-datapackage`:
+This is the flow of how `check-datapackage` is used, or at least how
+properties flow through `check-datapackage` functions and classes.
 
 ```{mermaid}
 %%| label: fig-interface-flow
-%%| fig-cap: "Flow of functions and classes when using `check-datapackage`."
+%%| fig-cap: "Flow of inputs and outputs through the functions and classes of `check-datapackage`."
 %%| fig-alt: "A flowchart showing the flow of using `check-datapackage`, starting with reading the `datapackage.json` and `.cdp.toml` files, then checking the properties with the config, and finally explaining any issues found."
 flowchart TD
     descriptor_file[(datapackage.json)]
@@ -231,7 +224,7 @@ flowchart TD
     read_config["read_config()"]
 
     config[/Config/]
-    custom_check[/CustomCheck/]
+    extensions[/Extensions/]
     exclusion[/Exclusion/]
     check["check()"]
     issues[/"list[Issue]"/]
@@ -240,9 +233,9 @@ flowchart TD
     messages[/messages/]
 
     descriptor_file --> read_json --> properties
-    config_file --> read_config --> config
-    custom_check & exclusion --> config
-    custom_check & exclusion -.-> config_file
+    config_file -.-> read_config -.-> config
+    extensions & exclusion --> config
+    extensions & exclusion -.-> config_file
 
     properties & config --> check --> issues --> explain --> messages
 ```