From 98e9e54bedfc2822d8fb0a999d7f38204dda613f Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sat, 2 Mar 2019 10:49:26 -0600 Subject: [PATCH 1/6] Review and revise context-narrative --- .../State-of-PureScript-Documentation-2019.md | 38 +++++++++---------- 1 file changed, 18 insertions(+), 20 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 04f3d83..f6a828f 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,41 @@ 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 +- Explore where PureScript's documentation is lacking and what can be done to improve it - 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. - -So, it helps to understand what is "good" documentation and why. +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'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. The intended audience +2. The type of documentation: the question being answered, targeting a specific subsection of the audience +3. How accurately it reflects the desired version of the thing being documented ### 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: -| Getting Started | Teaching a child how to cook | -| How-To Guides | Following a cook book's recipe | -| Explanation | Listening to a CEO answer questions about his company | -| Reference | Reading an encyclopedia | +| Learner's Phase | Type | Analogy | Characteristics +| -- | -- | -- | -- | +| Curious Outsider | The Hook | Selling a product to a potential customer | Answers these questions: +| Looking and Feeling the Product | Getting Started | Teaching a child how to cook | +| Testing the Product | How-To Guides | Following a cookbook's recipe | +| Discussing Design Details During Adoption | Explanation | Listening to a CEO answer questions about his company | +| Consulting Product Vocabulary Dictionary Post-adoption | Reference | Reading an encyclopedia | 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 From a6322222649b76274411deb134e5e05632eb80d0 Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sat, 2 Mar 2019 13:16:31 -0600 Subject: [PATCH 2/6] Adjust per review --- .../State-of-PureScript-Documentation-2019.md | 11 ++++++----- 1 file changed, 6 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 f6a828f..8e74d22 100644 --- a/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md +++ b/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md @@ -17,7 +17,8 @@ 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 -- Explore where PureScript's documentation is lacking and what can be done to improve it +- Explain why PureScript's documentation isn't developing as fast as wanted +- Develop plans to improve the current documentation strategy or process - 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? @@ -39,10 +40,10 @@ First, there are 5 types of documentation that target specific phases of a learn | Learner's Phase | Type | Analogy | Characteristics | -- | -- | -- | -- | | Curious Outsider | The Hook | Selling a product to a potential customer | Answers these questions: -| Looking and Feeling the Product | Getting Started | Teaching a child how to cook | -| Testing the Product | How-To Guides | Following a cookbook's recipe | -| Discussing Design Details During Adoption | Explanation | Listening to a CEO answer questions about his company | -| Consulting Product Vocabulary Dictionary Post-adoption | Reference | Reading an encyclopedia | +| 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 | Moreover, there are clear examples of "bad" documentation (as explained in [Teach, Don't Tell](http://stevelosh.com/blog/2013/09/teach-dont-tell/)): From 056e6e70b43eb4ac5bac5c00225883488f7a3e95 Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sat, 2 Mar 2019 13:21:36 -0600 Subject: [PATCH 3/6] Adjust the outline part per review --- .../State-of-PureScript-Documentation-2019.md | 4 ++-- 1 file changed, 2 insertions(+), 2 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 8e74d22..7f3bad1 100644 --- a/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md +++ b/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md @@ -17,8 +17,8 @@ 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 isn't developing as fast as wanted -- Develop plans to improve the current documentation strategy or process +- Explain why PureScript's documentation is seen as lacking +- Suggest plans to improve the current documentation strategy or process - 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? From 9945e6bf1a25e2e556387c97f2284eda413adc4a Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sat, 2 Mar 2019 13:28:13 -0600 Subject: [PATCH 4/6] Update State-of-PureScript-Documentation-2019.md --- .../State-of-PureScript-Documentation-2019.md | 2 +- 1 file changed, 1 insertion(+), 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 7f3bad1..a1c9253 100644 --- a/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md +++ b/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md @@ -18,7 +18,7 @@ Outline - Explain what "good" documentation is and define a criteria - Evaluate PureScript's documentation using that criteria - Explain why PureScript's documentation is seen as lacking -- Suggest plans to improve the current documentation strategy or process +- 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? From 2a657c7a877e985215cec38aee113985ebb1229f Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sat, 2 Mar 2019 13:43:12 -0600 Subject: [PATCH 5/6] Change to use "it" --- .../State-of-PureScript-Documentation-2019.md | 6 +++--- 1 file changed, 3 insertions(+), 3 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 a1c9253..5606716 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 @@ Outline 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'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 intended audience -2. The type of documentation: the question being answered, targeting a specific subsection of the audience -3. How accurately it reflects the desired version of the thing being documented +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 From 533d14ad3392909b9c2af6b3a33ca01d7e932c2a Mon Sep 17 00:00:00 2001 From: Alex Berg Date: Sat, 2 Mar 2019 13:44:20 -0600 Subject: [PATCH 6/6] Update State-of-PureScript-Documentation-2019.md --- .../State-of-PureScript-Documentation-2019.md | 4 +++- 1 file changed, 3 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 5606716..88f654e 100644 --- a/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md +++ b/02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md @@ -26,7 +26,9 @@ Outline ## 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. So, it's useful to learn a definition of good documentation and understand why it's defined that way. +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