Write the Context/Narrative

02-Context-or-Narrative/Good-Documentation.md

@@ -0,0 +1,135 @@
+# Good Documentation
+
+- [What is "Good" Documentation Anyway?](#what-is-good-documentation-anyway)
+- [The Types of Documentation](#the-types-of-documentation)
+- [The Documentation's Intended Audience](#the-documentations-intended-audience)
+- [Maintaining Documentation's Accuracy](#maintaining-documentations-accuracy)
+  - [The "Size" of a Change](#the-size-of-a-change)
+  - [The "Frequency" of a Change](#the-frequency-of-a-change)
+  - [How to Make Maintenance Easier](#how-to-make-maintenance-easier)
+- [Criteria for "Good" Documentation](#criteria-for-good-documentation)
+
+(The above Table of Contents was generated by: http://tableofcontent.eu)
+
+## What is "Good" Documentation Anyway?
+
+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.
+
+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. 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
+
+It's important to note that this section is sourced from only two blog posts, [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/). As we learn more this section might change in significant ways, so any conclusions we draw should be kept "flexible".
+
+## 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/))
+
+| Learner's Phase | Type | Analogy | Characteristics
+| -- | -- | -- | -- |
+| Curious Outsider | The Hook | Selling a product to a potential customer | Answers these questions: <ul><li>What is this thing? / What problem does it solve?</li><li>Why whould I care? / How is this relevant to me for my purposes? / Who should not care?</li><li>How long will it take to learn it and how difficult is the learning curve?</li><li>Where do I go to get started / learn how to use this?</li></ul>
+| 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>
+
+Moreover, there are clear examples of "bad" documentation (as explained in [Teach, Don't Tell](http://stevelosh.com/blog/2013/09/teach-dont-tell/)):
+
+| Documentation Source | Why it's bad |
+| -- | -- |
+| 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
+
+Second, the number of intended audiences can vary greatly. For example, here are different ways of categorizing them:
+- The language/paradigms they primarily use and think in (e.g. JavaScript, Ruby, Haskell; lazy, strict; OO, FP; etc.)
+- The amount of experience they have (e.g. never coded before, junior, senior, etc.)
+- The programs they are looking to create (e.g. games, financial applications, cryptography, etc.)
+
+Writing documentation that targets JavaScript-background junior developers who want to write games will focus on some things, exclude others, and order its content in a way that makes most sense to that purpose.
+
+As a result, others who read the resulting documentation will consider it "poor" in some aspect:
+- If one comes from a non-JavaScript language, one might find references to features in JavaScript confusing: "They used the concept of 'prototypes' to explain something, but that left me even more confused..." ~ a Java developer
+- If one comes from a different experience level, one might have unanswered questions: "They didn't even mention what the performance trade-offs for specific libraries were..." ~ a senior developer
+- If one has a different goal in mind, some crucial libraries might never be covered: "They didn't explain how I can make my Bitcoin client cryptographically secure..."
+
+## Maintaining Documentation's Accuracy
+
+Third, documentation becomes outdated/inaccurate when the thing being documented changes in two ways:
+- the 'size' of a change
+- the 'frequency' of changes
+
+### The "Size" of a Change
+
+The 'size' of a change can decrease its usefulness.
+
+| "Size" | Example
+| -- | -- |
+| Small | A bug fix that affects little else.
+| Medium | A new feature
+| Large | One or more breaking changes affecting numerous things simultaneously
+
+When breaking changes occur, documentation can immediately become useless because:
+- none of its code examples work anymore
+- old terms might mean something different now
+- some new parts may need be written
+- some parts of the documentation might no longer be relevant
+- one needs to figure out how to integrate new content into old content
+
+Updating documentation in light of breaking changes often requires the most work to update.
+
+### The "Frequency" of a Change
+
+The 'frequency' of a change can decrease its coherence.
+
+| "Frequency" | Example
+| -- | -- |
+| Rarely | Stable libraries that have exhausted their design space (e.g. core data types)
+| Sometimes | Maturing libraries that still have a few things to fix or add
+| Frequently | New libraries
+
+When changes occur frequently, documentation can appear more like loosely-coupled snippets of ideas rather than a coherent explanation because:
+- Article A depends on Article B to explain something. Then, Article B becomes outdated. Thus, one "patches" Article A with a quick overview of Article B that doesn't fit in with the rest of Article A's content.
+- One updates 3 out of 10 articles. One article says `X is true` whereas another says `X is false`. A new learner isn't sure which is correct.
+
+Updating documentation in light of frequent changes often requires less overall work.
+
+### How to Make Maintenance Easier
+
+Moreover, when breaking changes occur frequently, it discourages people from updating the documentation. Why waste time on something that will become outdated soon?
+
+The nature of this problem is not going to change. So, what medium of documentation provides the most "bang for your buck" long-term that is also is easiest to update?
+
+Heavily-commented code examples.
+
+It follows the principle of "show, don't tell." People can use them as a model from which to learn and as a playground on which to experiment.
+
+Other mediums of documentation (e.g. blog posts, literate programming, videos) each have their place. However, the code examples might produce the easiest-to-update documentation in the shortest time possible.
+
+Lastly, some documentations tasks are tedious and consume lots of time. Finding ways to automate them can greatly improve the situation.
+
+## Criteria for "Good" Documentation
+
+In short, it is impossible to write "good" documentation for everyone that is always up-to-date. There's simply not enough manpower, time, and incentives to do that. Rather, it will be "good", "horrible", or "somewhere in-between" for diffent kinds of people and at different times/seasons.
+
+Still, we can define our criteria for "good" documentation using these four factors. Documentation is "good" when:
+- [Type]
+    - It states which type of documentation it is
+    - It abides by that type's characteristics
+- [Audience]
+    - It states who the intended audience is
+    - For those who aren't the intended audience, it refers to other material that better suits them
+- [Accuracy]
+    - It tends to be heavier on code examples rather than other mediums
+    - It explains which version of the code it documents
+        - If it's not the most recent version, it provides:
+            - A brief idea of where it is outdated
+            - Guidelines for how to understand the outdated explanation in light of new changes
+    - It includes the date it was published and when it was last updated
+    - It indicates whether it will be updated in the future (and when) or has been abandoned and no future updates will occur.

02-Context-or-Narrative/Our-Outcome-Ideas.md

@@ -0,0 +1,96 @@
+# Our Outcome Ideas
+
+The below Table of contents was generated by http://tableofcontent.eu
+
+- [Goal: The top 30 dependencies used in PS' ecosystem have examples and counterexamples in all of their Pursuit docs.](#goal-the-top-30-dependencies-used-in-ps-ecosystem-have-examples-and-counterexamples-in-all-of-their-pursuit-docs)
+  - [How: A community-curated "ACME" Spago project](#how-a-community-curated-acme-spago-project)
+- [Goal: Collect the best and clearest explanations for FP concepts into a central location](#goal-collect-the-best-and-clearest-explanations-for-fp-concepts-into-a-central-location)
+  - [How: Add it to Jordan's learning repository](#how-add-it-to-jordans-learning-repository)
+- [Goal: Convert all answered Slack-based questions into StackOverflow Questions and Answers](#goal-convert-all-answered-slack-based-questions-into-stackoverflow-questions-and-answers)
+  - [How: Reask and reanswer it on StackOverflow](#how-reask-and-reanswer-it-on-stackoverflow)
+- [Goal: Collect the best solutions to common build-related problems into a central location](#goal-collect-the-best-solutions-to-common-build-related-problems-into-a-central-location)
+  - [How: Add it to a special "build" repository](#how-add-it-to-a-special-build-repository)
+- [Goal: Add Syntax Examples for Core Libraries](#goal-add-syntax-examples-for-core-libraries)
+  - [How: Document a syntax example in Jordan's Learning Repo](#how-document-a-syntax-example-in-jordans-learning-repo)
+- [Goal: Document "best practices" for writing a good bindings library.](#goal-document-best-practices-for-writing-a-good-bindings-library)
+  - [How: ???](#how)
+
+## Goal: The top 30 dependencies used in PS' ecosystem have examples and counterexamples in all of their Pursuit docs.
+
+### How: A community-curated "ACME" Spago project
+
+We make a version of Justin Woo's "ACME" Spago project ([project](https://github.com/justinwoo/acme-spago) & [resulting docs](https://jusrin.dev/acme-spago/)). For packages that are lacking docs or are maintained by core contributors who won't respond quickly, we could use Spago to override those packages with a version supplied by a community member that includes more documentation.
+
+All changes should be accepted with little questioning. However, the project should heavily warn against people using the resulting package set in production as one could easily introduce malware here.
+
+## Goal: Collect the best and clearest explanations for FP concepts into a central location
+
+In general, these are the kinds of things I had in mind:
+- What are some of the clearest explanations of FP concepts?
+- How hard is it to port their code examples to PureScript?
+- Have people written an explanation that "walks one through" an FP paper's ideas in a clear way?
+
+I don't want another 'link farm.' That leads to information overload and decision paralysis.
+
+Rather, I want the top 1 or 2 explanations on something.
+
+### How: Add it to Jordan's learning repository
+
+These links could be added to [Jordan's learning repo](http://www.github.com/jordanmartinez/purescript-jordans-reference) as it exists partly for this purpose.
+
+While lacking expertise in some areas, he can still sift through them and help determine which are great, good, duplicates, or just downright bad.
+
+## Goal: Convert all answered Slack-based questions into StackOverflow Questions and Answers
+
+Slack is still an ideal place to ask a question. However, it doesn't persist.
+
+### How: Reask and reanswer it on StackOverflow
+
+When a question on the `#purescript` or `#purescript-beginner` Slack channel gets answered, request the person who asked it to post the question on StackOverflow and link to the question in the chatroom.
+
+Then, let someone (whether the answerer or someone who saw it) "answer" that question and give credit it to the answerer.
+
+We should prioritize persistent docs over crediting who answered the question.
+
+## Goal: Collect the best solutions to common build-related problems into a central location
+
+- Integrating PureScript to work with JS build tools?
+- Integrating PureScript with CI (Travis, AppVeyor, etc.)?
+- Possible "tree-shaking" approaches to PureScript and their tradeoffs?
+
+### How: Add it to a special "build" repository
+
+I would suggest adding it to Jordan's learning repo, but this idea only works well if there are lots of small sample projects to build. Thus, it'd be better kept as its own repository.
+
+## Goal: Add Syntax Examples for Core Libraries
+
+Sometimes, Pursuit docs don't help you know how to use something. However, a lot can be gleaned/imitated by looking at an example. For example:
+- [Halogen's "basic button component" example](https://github.com/slamdata/purescript-halogen/blob/master/examples/basic/src/Button.purs)
+- [Jordan's example for how to create a tree via `purescript-tree`](https://github.com/JordanMartinez/purescript-jordans-reference/blob/latestRelease/22-Projects/src/11-Table-of-Contents/04-Tree/01-Syntax.purs#L31-L64)
+- [Jordan's example of the "hello world" program via the ReaderT design pattern](https://github.com/JordanMartinez/purescript-jordans-reference/blob/latestRelease/21-Hello-World/08-Application-Structure/src/11-Hello-World/02-ReaderT.purs)
+
+### How: Document a syntax example in Jordan's Learning Repo
+
+I've begun to do this myself [here](https://github.com/JordanMartinez/purescript-jordans-reference/tree/latestRelease/22-Projects/src/01-Libraries) with a few libraries that I've used when building some projects. Perhaps I will later turn this into a separate top-level folder and call it "cookbook"
+
+## Goal: Document "best practices" for writing a good bindings library.
+
+```
+Worst ---------- Ok ---------------------------- Great
+No libraries     Bindings to JS library          PS library
+```
+While JS library bindings aren't ideal, they can still solve a problem quickly. Knowing how to write a good bindings library can help make the PS ecosystem that much more mature.
+
+Some questions people might ask:
+- How should a library author analyze the library to which they want to write bindings?
+- What are common problems such people face and their possible solutions?
+
+ ### How: TBD
+
+## Goal: Improve guides for how to test applications / test libraries
+
+Inspired by [this comment](https://github.com/JordanMartinez/purescript-jordans-reference/issues/280#issuecomment-485144396), producing a stable library or finished application could be slowed down if writing tests get slowed down by small issues like this.
+
+ ### How: TBD
+
+One idea is to write more convenience functions that make it easier to generate the `String`s we need.