From 773cd579568842be72af54ed5cbbd71eb03955c4 Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sun, 5 May 2019 13:39:34 -0500 Subject: [PATCH 1/2] Update State-of-PureScript-Documentation-2019.md --- .../State-of-PureScript-Documentation-2019.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) 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 b751ecf..8670075 100644 --- a/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md +++ b/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md @@ -29,9 +29,9 @@ Do not misinterpret the below table as a linear progression from Curious Outside | Potential User | Getting Started | Teaching a child how to cook | | New User | How-To Guides | Following a cookbook's recipe | | Active User | Reference | Reading an encyclopedia | -| Experienced User | Explanation | Listening to a CEO answer questions about his company | +| Experienced User | Explanation | Listening to a CEO answer questions about his company | -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 clearly "bad", (as explained in [Teach, Don't Tell](http://stevelosh.com/blog/2013/09/teach-dont-tell/)): | Documentation Source | Why it's bad | | -- | -- | @@ -44,7 +44,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 +84,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]() From 43f55bdeeaa00b2ac6ef07ff3fe5cdd91f506a9d Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sun, 12 May 2019 20:42:57 -0500 Subject: [PATCH 2/2] Adjust reason for bad documentation --- .../State-of-PureScript-Documentation-2019.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) 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 8670075..470c196 100644 --- a/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md +++ b/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md @@ -31,7 +31,11 @@ Do not misinterpret the below table as a linear progression from Curious Outside | Active User | Reference | Reading an encyclopedia | | Experienced User | Explanation | Listening to a CEO answer questions about his company | -It's also important to take note of forms of documentation which are clearly "bad", (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 | | -- | -- |