Update State-of-PureScript-Documentation-2019.md

02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md

@@ -29,9 +29,13 @@ Do not misinterpret the below table as a linear progression from Curious Outside
 | Potential User | Getting Started | Teaching a child how to cook | <ul><li>Focuses on the learner 'doing' stuff, not 'explaining' stuff to the learner</li><li>Provides a small simple working example that teaches the basics</li><li>New learners experience an 'I can use this now!' moment by the end</li><li>Focuses on concrete tasks, not abstract concepts</li><li>Does not use jargon</li><li>Explains only what is necessary and cuts out all else</li><li>Avoids explaining deeper concepts or different ways of doing the same thing</li></ul>
 | New User | How-To Guides | Following a cookbook's recipe | <ul><li>Achieves some goal or solves a problem</li><li>States the pre-requisites one needs to have before starting (not a Getting Started Guide)</li><li>The Guide follows a clearly-labeled step-by-step process</li><li>By following the steps, one reproduces the same results without fail</li><li>Explains the different ways one can achieve the same goal</li><li>Explains only what is necessary</li></ul>
 | Active User | Reference | Reading an encyclopedia | <ul><li>Concise explanation of each piece of the code</li><li>The structure of the reference mirrors the structure of the code it documents</li><li>Formatting is consistent throughout the material</li></ul>
-| Experienced User | Explanation | Listening to a CEO answer questions about his company | <ul><li>Explains the context/history</li><li>Explains the significant design decisions made, their alternativees, and the reasons one was chosen over another</li><li>Implies where things could be improved, expanded, refined, etc.</li></ul>
+| Experienced User | Explanation | Listening to a CEO answer questions about his company | <ul><li>Explains the context/history</li><li>Explains the significant design decisions made, their alternatives, and the reasons one was chosen over another</li><li>Implies where things could be improved, expanded, refined, etc.</li></ul>
 
-Moreover, there are clear examples of "bad" documentation (as explained in [Teach, Don't Tell](http://stevelosh.com/blog/2013/09/teach-dont-tell/)):
+It's also important to take note of forms of documentation which are "bad". In [Teach, Don't Tell](http://stevelosh.com/blog/2013/09/teach-dont-tell/), the author states:
+
+> The purpose of technical documentation is to take someone who has never seen your project, teach them to be an expert user of it, and support them once they become an expert.
+
+From this, we identify the following forms of documentation as being a poor means of accomplishing that goal:
 
 | Documentation Source | Why it's bad |
 | -- | -- |
@@ -44,7 +48,9 @@ Note: this section is sourced from only two blog posts, [What Nobody Tells You A
 
 ## Assessing PureScript's Documentation
 
-Below, we tagged each documentation effort with its documentation type (if yours isn't listed or is incorrect, notify us). By looking at what exists, we can see that the following types of documentation might need more improvement:
+Now that we have defined what PureScript's documentation *should* look like, what does PureScript *currently* have for documentation?
+
+Below, we tagged each documentation effort with its documentation type (if yours isn't listed or is incorrect, notify us). By seeing this, it looks like the following types of documentation might need more improvement:
 - Hooks
 - How-To Guides
 - Explanations
@@ -82,9 +88,9 @@ Here's the short version. Each paragraph will have a link that explains its summ
 
 It is difficult to define what are FP's "best practices / design patterns." The issues explained below are mostly situational; they will improve in time. However, this "best practices" issue is hard to address because it is subjective in nature, requires a lot of expertise, and requires a great communicator. [further explained here]()
 
-PureScript is not _currently_ trying to be the next "mainstream language." Rather, it values "power" over "popularity" and so works towards those ends. [further explained here]()
+PureScript is not _currently_ trying to be the next "mainstream language," which prioritizes onboarding new users. Rather, it values "power" over "popularity" and so works towards those ends. [further explained here]()
 
-While developing the language, core contributors incurred a lot of responsibility (e.g. library maintenance, documentation updates, updating Pursuit and other related sites, etc.). Over time, they became spread thin and one even burned out. [further explained here]()
+While developing the language, core contributors incurred a lot of responsibility (e.g. library maintenance, documentation updates, and updating Pursuit and other related sites). Over time, they became spread thin and one even burned out. [further explained here]()
 
 Thus, they cannot quickly respond to most people's questions or contributions. With the small amount of time they do have, they are focusing on adding new language features, not improving the documentation situation. The language's development is steady (6-week release cycle) but slow. Moreover, only some of them have write/deploy access to key documentation infrastructure (e.g. Pursuit, documentation repo, Try PureScript, etc.) [further explained here]()