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: -| 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: +| 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/)): -| 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