-
Notifications
You must be signed in to change notification settings - Fork 0
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Review and revise context-narrative #51
Merged
JordanMartinez
merged 6 commits into
context-narrative
from
chexxor-context-narrative-review
Mar 2, 2019
Merged
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
98e9e54
Review and revise context-narrative
chexxor a632222
Adjust per review
chexxor 056e6e7
Adjust the outline part per review
chexxor 9945e6b
Update State-of-PureScript-Documentation-2019.md
chexxor 2a657c7
Change to use "it"
chexxor 533d14a
Update State-of-PureScript-Documentation-2019.md
chexxor File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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: <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> | ||
| 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> | ||
| How-To Guides | Following a cook book'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> | ||
| 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> | ||
| 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> | ||
| 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/)): | ||
|
||
| Statement | Why it's bad | | ||
| Documentation Source | Why it's bad | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ah... yeah, that's a better column heading |
||
| -- | -- | | ||
| 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 | ||
|
||
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like this change. It provides a better starting point that clarifies the other columns and their content.
Still, perhaps it should be rendered as "The Learner" to reflect the concept of a learner's identity (see my other comments below for more context)?