diff --git a/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md b/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md
index 04f3d83..88f654e 100644
--- a/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md
+++ b/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md
@@ -17,43 +17,44 @@ It is well-known among the PureScript community that its documentation is lackin
Outline
- Explain what "good" documentation is and define a criteria
- Evaluate PureScript's documentation using that criteria
-- Explain why PureScript's documentation is lacking and what is being done to improve it
+- Explain why PureScript's documentation is seen as lacking
+- Suggest plans to improve the current documentation situation
- Address various audience's possible concerns or questions centered on these themes:
- New learners - How should I learn PureScript?
- PureScript documentation writers - How should I write good maintainable documentation for others?
- - Core Contributors -
+ - Core Contributors -
## What is "Good" Documentation Anyway?
-Did someone ever teach you how to write "good" documentation? No, you likely just wrote what came to mind and hoped it was good enough.
+Did someone ever teach you how to write "good" documentation? Probably not - you likely just wrote what came to mind and hoped it was good enough.
-So, it helps to understand what is "good" documentation and why.
+Because of this, it's useful to learn a definition of good documentation and understand why it's defined that way.
Essentially, there are 3 factors that affect whether documentation is "good" or not.
-1. The type of documentation
-2. The intended audience
-3. How up-to-date the documentation is
+1. Its intended audience
+2. Its type: the question being answered, targeting a specific subsection of the audience
+3. How accurately it reflects the desired version of the code/project
### The Types of Documentation
First, there are 5 types of documentation that target specific phases of a learner's experience (as explained in [What Nobody Tells You About Documentation](https://www.divio.com/blog/documentation/) and [Teach, Don't Tell](http://stevelosh.com/blog/2013/09/teach-dont-tell/))
-| Type | Analogy | Characteristics
-| -- | -- | -- |
-| The Hook | Selling a product to a potential customer | Answers these questions:
- What is this thing? / What problem does it solve?
- Why whould I care? / How is this relevant to me for my purposes? / Who should not care?
- How long will it take to learn it and how difficult is the learning curve?
- Where do I go to get started / learn how to use this?
-| Getting Started | Teaching a child how to cook | - Focuses on the learner 'doing' stuff, not 'explaining' stuff to the learner
- Provides a small simple working example that teaches the basics
- New learners experience an 'I can use this now!' moment by the end
- Focuses on concrete tasks, not abstract concepts
- Does not use jargon
- Explains only what is necessary and cuts out all else
- Avoids explaining deeper concepts or different ways of doing the same thing
-| How-To Guides | Following a cook book's recipe | - Achieves some goal or solves a problem
- States the pre-requisites one needs to have before starting (not a Getting Started Guide)
- The Guide follows a clearly-labeled step-by-step process
- By following the steps, one reproduces the same results without fail
- Explains the different ways one can achieve the same goal
- Explains only what is necessary
-| Explanation | Listening to a CEO answer questions about his company | - Explains the context/history
- Explains the significant design decisions made, their alternativees, and the reasons one was chosen over another
- Implies where things could be improved, expanded, refined, etc.
-| Reference | Reading an encyclopedia | - Concise explanation of each piece of the code
- The structure of the reference mirrors the structure of the code it documents
- Formatting is consistent throughout the material
+| Learner's Phase | Type | Analogy | Characteristics
+| -- | -- | -- | -- |
+| Curious Outsider | The Hook | Selling a product to a potential customer | Answers these questions: - What is this thing? / What problem does it solve?
- Why whould I care? / How is this relevant to me for my purposes? / Who should not care?
- How long will it take to learn it and how difficult is the learning curve?
- Where do I go to get started / learn how to use this?
+| Potential User | Getting Started | Teaching a child how to cook | - Focuses on the learner 'doing' stuff, not 'explaining' stuff to the learner
- Provides a small simple working example that teaches the basics
- New learners experience an 'I can use this now!' moment by the end
- Focuses on concrete tasks, not abstract concepts
- Does not use jargon
- Explains only what is necessary and cuts out all else
- Avoids explaining deeper concepts or different ways of doing the same thing
+| New User | How-To Guides | Following a cookbook's recipe | - Achieves some goal or solves a problem
- States the pre-requisites one needs to have before starting (not a Getting Started Guide)
- The Guide follows a clearly-labeled step-by-step process
- By following the steps, one reproduces the same results without fail
- Explains the different ways one can achieve the same goal
- Explains only what is necessary
+| Active User | Reference | Reading an encyclopedia | - Concise explanation of each piece of the code
- The structure of the reference mirrors the structure of the code it documents
- Formatting is consistent throughout the material
+| Experienced User | Explanation | Listening to a CEO answer questions about his company | - Explains the context/history
- Explains the significant design decisions made, their alternativees, and the reasons one was chosen over another
- Implies where things could be improved, expanded, refined, etc.
Moreover, there are clear examples of "bad" documentation (as explained in [Teach, Don't Tell](http://stevelosh.com/blog/2013/09/teach-dont-tell/)):
-| Statement | Why it's bad |
+| Documentation Source | Why it's bad |
| -- | -- |
-| Read the Source Code | Only useful once you are already familiar with it
-| Read the Test Code | While it uses the code, it tends to focus on edge cases, not normal cases, and may not use all possible options/configurations.
-| Read the API docs | One must know the name of the function/value to be able to read its documentation. Most won't know the name until you teach it to them. Likewise, people don't learn by reading alphabetized lists of disconnected information
-| Read the Wiki | Content is usually not written by the code's authors, but by multiple 3rd-party people. There are often multiple disconnected voices throughout the material. It's like asking a student to write his own lesson plan.
+| Source Code | Only useful once you are already familiar with it
+| Test Code | While it uses the code, it tends to focus on edge cases, not normal cases, and may not use all possible options/configurations.
+| API docs | One must know the name of the function/value to be able to read its documentation. Most won't know the name until you teach it to them. Likewise, people don't learn by reading alphabetized lists of disconnected information
+| Wiki | Content is usually not written by the code's authors, but by multiple 3rd-party people. There are often multiple disconnected voices throughout the material. It's like asking a student to write his own lesson plan.
### The Documentation's Intended Audience