Review and revise context-narrative #51
Conversation
There was a problem hiding this comment.
I agree with practically all of these changes. A few things could be edited though that might make things clearer or easier to understand.
For example, 'The Learner's Phase' column in the table that indicates types of documentation could better emphasize the learner's identity (who is the learner at this point?) rather than carry the "sales" theme that currently permeates it.
| @@ -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 | |||
There was a problem hiding this comment.
I think the 'why' should be kept as it implies we'll be explaining something / answering a question. The 'where' sort of implies the areas where it is lacking and might miss the overall picture I think we're trying to cover here.
'is being' explains what's already out there so others can support it rather than start their own thing. Still, 'can be' implies that there are some improvements we aren't already doing. So, perhaps we should include both of these?
"... is lacking, what is being done to improve it, and what can still be done to improve it."
There was a problem hiding this comment.
When I hear "is being done" I hear "someone else is actively doing" which implies (to me) that my help isn't needed. I think an open-source project should communicate in a way which implies the project is a work-in-progress and it consists of a to-do list that anyone can work on.
I'll brainstorm some options as post a follow-up comment.
There was a problem hiding this comment.
- Explain why PureScript's documentation isn't developing as fast as wanted and describe how to improve it
- Explain why PureScript's documentation is lacking and explain the current development plans
- Explain why PureScript's documentation is lacking and develop plans to improve the current strategy
There was a problem hiding this comment.
When I hear "is being done" I hear "someone else is actively doing" which implies (to me) that my help isn't needed.
Ah... good point. I read that, too, now that you bring that up.
There was a problem hiding this comment.
Thanks for the other ways to render this. It provides other points to consider.
Explain why PureScript's documentation isn't developing as fast as wanted...
That is an issue in the documentation, but I think that is covered later in the document. I think 'lacking' is the best overall description because it doesn't explain what is lacking. Are we lacking documentation period? Is the current documentation lacking organization or clarity? It simply communicates things aren't the way they should be.
describe how to improve it
'describe' is perhaps not the best word to use her. Perhaps 'suggest' because here are the conclusions we've made, but readers might have other ideas?
explain the current development plans
This assumes there are such plans and without a mutually-held vision, I don't think it would be wise so say that.
develop plans to improve the current strategy
Hmm... that's good rendering in at least one aspect. It sort of implies that we want people to get involved: "discuss and develop plans ..."
"the current strategy" implies there is one, and again I don't know if there is. Maybe it should just be "plans to improve the current situation."
There was a problem hiding this comment.
Good ideas. I've updated this part just now. I also broke it into two parts, because it seems to be the right thing to do here, but I'm not sure whether that'll fit the implementation of this outline later on in this document.
| 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. |
There was a problem hiding this comment.
I actually broke this up intentionally. It may not 'help the flow' as much (good point), but it makes it easier to skim. Depending on how long this document is, if we don't grab the reader's attention strongly-enough, it won't matter what we say.
Then again, I don't know if this one sentence is worth standing out in place of others...
There was a problem hiding this comment.
That makes sense. I'll review that aspect of your strategy here and post a follow-up comment. 👍
There was a problem hiding this comment.
Yeah, I think I like your approach here better. I'll revert and change from "So" to "Because of this", which I think will make it "stronger" and better able to stand on its own.
There was a problem hiding this comment.
I think Thus would have done the same thing ;-) but I merged it so I can move on to the next part.
We can review this again before posting as then the rough draft of the document will be finished.
| 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 |
There was a problem hiding this comment.
Hmm... I think that having the intended audience come before the type makes more sense. Good idea!
How accurately it reflects the desired version of the thing being documented
I think this rendering explains the idea I was trying to convey better. However, could this be reworded or rendered differently somehow. I feel like it's still a bit too complicated. Maybe "How accurately it documents the desired version of the code/project" ? "thing" isn't as concrete as 'code'/'project', especially in this context
There was a problem hiding this comment.
I like the term "reflects" because I believe it properly relates documentation to the thing its documenting. A thing and its reflection should be "the same" in some sense. How a thing behaves and how its documentation reflects that behavior should be "the same", but the documentation is expected to add, for example, information and context to make the behavior easy to understand and remember.
I think both are fine here, however, and I like how you cleaned it up.
- "How accurately it reflects the desired version of the code/project"
- "How accurately it documents the desired version of the code/project"
There was a problem hiding this comment.
Mm... good point on the 'reflection' concept.
However, "it" in this context is not that clear. In the first two points above this one, we never mention "it" If we were more specific with what 'it' means it would look like this:
"How accurately the documentation reflects the desired version of the code/project" ?
However, once it's rendered like that, it seems odd to describe 'documentation' as 'reflecting' something rather than 'explaining' it. Does it still work? Yes, but I don't think it's the best rendering still.
One way we could address this is to use 'it' in every point, so that it now reads (full context):
Essentially, there are 3 factors that affect whether documentation is "good" or not.
- Its intended audience
- Its type: the questions being answered, targeting a specific subsection of the audience
- How accurately it reflects the desired version of the code/project
There was a problem hiding this comment.
Very nice. I've updated to use "it".
| | 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 |
There was a problem hiding this comment.
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)?
| | 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> | ||
| | Looking and Feeling the Product | 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> |
There was a problem hiding this comment.
Having read the column header "Learner's Phase" and the first row "Curious Outsider" as a "Learner's Identity", "Looking and Feeling the Product" doesn't seem to fit.
Rather, I imagine that the person is now "dating" the library to see whether it's a good fit. They haven't quite "bought the product" yet, but they haven't dismissed it either.
Perhaps it should be rendered as "Potential User" ?
| | -- | -- | -- | -- | | ||
| | 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> | ||
| | Looking and Feeling the Product | 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> | ||
| | Testing the Product | 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> |
There was a problem hiding this comment.
I read "testing" like unit tests. So "testing the product" seems like it communicates something else.
I feel like a learner at this point has already 'bought' the product. Now they are just trying to figure out how to actually use it to improve their life in some way.
Perhaps it should be rendered as "New User" ?
| | 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> | ||
| | Looking and Feeling the Product | 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> | ||
| | Testing the Product | 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> | ||
| | Discussing Design Details During Adoption | 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> |
There was a problem hiding this comment.
Continuing with the theme of a learner's identity, perhaps render this as "Experienced User"
|
|
||
| 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.
Ah... yeah, that's a better column heading
| | Looking and Feeling the Product | 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> | ||
| | Testing the Product | 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> | ||
| | Discussing Design Details During Adoption | 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> | ||
| | Consulting Product Vocabulary Dictionary Post-adoption | 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> |
There was a problem hiding this comment.
Continuing with the theme of a learner's identity, I'm not sure how to render this content.
One idea was "Exploring technical details", but that states "what" one is doing, not "who" is doing it.
There was a problem hiding this comment.
Yeah, I've updated these phase names in the latest update here, so you can review those again.
|
I went with the sales theme for the phases of learner likely because "The Hook" was the first element of the first phase, and that sounds "sales-y" to me, haha. But I agree with your criticism of the analogy, because I think that analogy could erode the phases into an unexpected and undesirable state. |
Makes sense! It was fun to read because it started feeling like we were talking about how to better document a product than something else, haha! |
|
"User" and "Learner" are a bit synonymous here, right? Is it correct to interpret "user" as being a learner of our specific project? |
| @@ -17,43 +17,42 @@ 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 strategy or process | |||
There was a problem hiding this comment.
I'm being nitpicky here, but I think this should be rendered as "Suggest ways to improve the current documentation situation"
Strategy can be a part of that. Process can be a part of that. However, I don't want to presume we have the 'authority' to make such pronouncements or the 'power' to actually do it.
There was a problem hiding this comment.
Yeah I think that's appropriately ambiguous at this point. Good idea.
I am curious to see if someone discovers a learning phase that isn't included in this list. Perhaps "maintainer" is a separate one? Or "inventor of new tools"? Ha, I don't know. I am suspicious that this list of phases is rather biased in some way we should be aware of. I think it's biased in that it presumes an already-created system. While there is already a system in place, that system can be changed or grown by people. Is there a learners phase in which they contribute back to the project? Or in which they become up-to-date with changes to the project? |
|
I believe I've addressed all comments you've made. 👌 |
Hmm... Yeah, they are basically the same thing. A learner needs to learn something. However, they only need to learn something because, as a user, they don't know how to do something. I guess one becomes a 'user' before they become a 'learner.' (And, let's not go down that philosophical rabbit hole, haha!) |
I think that's a bit of a misunderstanding of the terms we're using here. The identity terms here simply communicate the 'intended audience' so to speak behind each type of documentation. They don't communicate the 'intended author' behind each type. Even a new learner can help contribute to documentation by explaining what did not make sense and why.
Relating to my point above, but maybe this also shows an 'intended author / qualified author/writer' aspect as well? |
|
Perhaps the 'intended author / qualified author' aspect might help people know what type of docs they could contribute. However, this doesn't account for the bottleneck they would experience due to core contributors' limited time. |
|
I'm merging this so I can continue to work on other things using the proposed workflow in #50 |
Just some changes I propose would improve clarity and flow.