Why docs are lacking

[JordanMartinez]

Still a WIP, but I'm getting closer to being done.

[JordanMartinez]

@chexxor I think this is 'good enough' for an initial review. There will be some obvious places it can be improved or changed.

[chexxor]

This is a good first review. I will likely want to review the second half more closely, and perhaps suggest ways of adding more "meat" to it, after we resolve this first review.

[chexxor]

I think there's some truth in that section, I just don't think "productivity" is the right word for it. I would guess it's similar to Haskell's values, and I saw you found one person's explanation of that. I'll take a look at the latest version later, though

…

On Wed, Mar 6, 2019, 1:57 PM JordanMartinez ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In 02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md <#53 (comment)> : > + +Many have wrongly assumed that PureScript is trying to replace [insert your favorite web language here]. That is not the case. Each language has its trade-offs that make it better for some and worse for others. + +Rather, PureScript is _currently_ following the motto of "**avoid (success at all costs)**". + +#### The Wrong Interpretation of 'Avoid (success at all costs)' + +One might understand 'avoid (success at all costs)' as "We don't want to be 'successful.' We don't want everyone to use this language. Therefore, let's make it hard and impractical for people to learn and use this language." + +New learners have likely said or thought, "Stupid language developers! Why didn't they make it easier to learn how to use this language and its abstractions? I thought this was a 'better' language." + +This interpretation is flawed because it focuses on the _wrong core values_: low learning curve and ease of use. PureScript's language developers do value these things, but they value other things more. + +#### The Right Interpretation of 'Avoid (success at all costs)' + +To understand this motto, one must understand the core value behind it: productivity: I decided just to delete this part. I don't think we need to argue why we think PureScript is 'more productive' than other languages. We're simply stating what it's philosophy is. We can refer to other documents here in place of making a statement ourselves. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#53 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAzdmRA-ugWrrenHaRugQVKamhkk3T1Hks5vUB24gaJpZM4basaI> .

[JordanMartinez]

I've done some more work on this. When we're ready to merge this (assuming review goes well), I'd like to turn each bullet point in the overview of its various subsections into anchor links to their sections.

[chexxor]

Copy-pasting from a comment thread into the PR thread for later reference and further discussion.

"The lines between language principles, personal preferences, and best practices is unclear" (This feels right, but I haven't thought deeply enough to settle on this being true. Also, I'd need to find examples for each of these three categories.)

For example, is a Monad a design pattern? I don't initially see it as such, but I guess it could be called that. At the same time, how else would you do something in FP without Monads?
Are phantom types design patterns? Should one always use smart constructors?

[chexxor]

The framework we are following puts this into the 02-Context-or-Narrative.md phase.

To ensure this project is still following the initial framework, I think it's worth looking at how this document fits into it.

Can we break this one big file into smaller files, one which answers each step of this process, in order? I think it would be more organized and easier to navigate & read. Following is an attempt at a file split.

- 010-Purpose.md (Copy section: ## Why Read This Document?)
- 011-Purpose-What-is-Good-Documentation.md (Copy section: ### What is "Good" Documentation Anyway?)
- 020-Obstacles-ReadMe.md (?)
- 021-Obstacles-PureScript-Documentation-Evaluation.md (Copy section: ## Why is PureScript's Documentation Lacking and How Do We Improve It?)
- 030-Result.md (Forecast a future of no action/status quo, and list the outcomes to use in the 04-Outcomes-Brainwrite-Next-Actions phase? Copy section: Summary of 'Why Docs are Lacking')

I'm reading the "Why is PureScript's Documentation Lacking and How Do We Improve It?" section while evaluating which parts are describing the obstacles and which are just describing the current situation... I can't find a specific section because I'm out of time right now, but IIRC it wasn't clear whether it is simply describing the situation or also prescribing solutions here. Is it appropriate to explore solutions here? Or is it best to do to that in a later phase?

[JordanMartinez]

I'm reading the "Why is PureScript's Documentation Lacking and How Do We Improve It?" section while evaluating which parts are describing the obstacles and which are just describing the current situation... I can't find a specific section because I'm out of time right now, but IIRC it wasn't clear whether it is simply describing the situation or also prescribing solutions here. Is it appropriate to explore solutions here? Or is it best to do to that in a later phase?

I think that's part of the issue right now: how much of this document should be descriptive (here's what is currently true about PS' docs) and how much of it should be suggestive (here's what we could do in this situation to improve it, but bring your own ideas).

In the back of my mind, the real issue has been something else: rather than writing just the "Context", I've been writing various parts from "Context" to "Outcome."

I think the "context" should be descriptive. It states what is true and helps inform what our purpose and principles and outcomes should be, but it does not define what those are. The document (as it currently stands) seems to be integrating the Context, Principles, and the Outcomes together. Take a look for yourself:

Context (what is true)

• what is good docs (corresponding section in current document)
• what are obstacles are ("why docs are lacking" section excluding suggestions for how to fix it)
• who are the people involved (core contribs, users of PS, doc writers, new learners of ps)
• what happens if we succeed: ?
• what happens if we fail: ?

Purpose (why are we trying to do something because Context is true?):

• (obvious) improve PS docs

Principles (how should it be done because Context is true?):

• abide by 'good docs' standards
• do it in a way that doesn't waste/distract core contrib's precious time (likely unofficial routes for now)
• share the work among people (prevent burnout and learn from history)
• improve existing docs rather than start from scratch

Outcome (what specifically must be accomplished for Purpose to be fulfilled?):

• better onboarding process (the "how should new learners learn in this context" section), suchas PS learners can read/write a smaller version of Thomas Honeyman's "Real World" Halogen app in 30 days or less
• docs adhere to good standards (the "how should doc writers write docs" section), such as "all PS documentation linked to in the docs repo abide by these standards.
• roadmap is defined (coordinated efforts arise, making this work occur faster/better), such as "By Dec 31, 2019, Language feature X will have been implemented, libraries Y and Z are production-ready, and other stuff here..."
• etc.

So I think your proposal to break this document up into smaller chunks is (in some ways) asking to break it up according to its spot in our methodology. Even if it's not, I think breaking it up would be easier to read as long as there are hyperlinks at the top/bottom that allow one to easily navigate to the next/previous one.

[chexxor]

@JordanMartinez Can you provide a link to another definition/explanation of the methodology we are following here? I did a search for "GTD methodology" and the result doesn't perfectly match with what we have here, though it is close. https://lifehacker.com/productivity-101-a-primer-to-the-getting-things-done-1551880955 I feel it's necessary for me to read more about this methodology to help make a decision here. On the other hand, perhaps you know enough about the methodology to recommend a resolution to this document length/complexity here.

update: Your answer will be nice to link to others who read/contribute to this project, something I intend to communicate in my task here: #56

For reference, here's the original post you made which described this methodology: https://discourse.purescript.org/t/purescript-documentation-efforts-in-2019/524/14

[chexxor]

After reading through this again, I think there was a misunderstanding on my side. This PR currently lists the problems, and I implicitly read that as "therefore fix these things" which sounds like proposing a solution. I think this is incorrect, however, because exploring strategies are how we solve problems and this PR doesn't include strategy exploration.

[JordanMartinez]

Can you provide a link to another definition/explanation of the methodology we are following here? I did a search for "GTD methodology" and the result doesn't perfectly match with what we have here, though it is close. https://lifehacker.com/productivity-101-a-primer-to-the-getting-things-done-1551880955 I feel it's necessary for me to read more about this methodology to help make a decision here. On the other hand, perhaps you know enough about the methodology to recommend a resolution to this document length/complexity here.

So, for context, the GTD methodology consists only of the Purpose to Next Actions stuff. So, reading what I wrote in your above link and in this repo's explanation of the methodology is accurate when you completely ignore the Sources and Context/Narrative aspects.

The Sources and Context/Narrative aspects are things I added on top of the model once I understood it. Why? Because I drew out the logic to its final conclusions and that's what I got:

Task Name	GTD?	"The level at which we think when..."
Next Actions	Yes	.... we are going to DO something now
Brainstorm	Yes	... we are trying to determine the step-by-step PLAN for how to achieve the outcome
Outcome	Yes	... we are trying to determine WHAT we are trying to achieve
Principles	Yes	... we are trying to determine general GUIDELINES for how to accomplish the purpose
Purpose	Yes	... we are trying to determine WHY we are trying to do something
Context	No	... we are trying to determine what caused the Purpose to even exist and when it will stop existing ... we are trying to become informed, so that we can define the Purpose, Principles, and Outcomes wisely
Sources	No	... we are trying to determine what data to use to construct the Context (e.g. which are credible, which are not, etc.)

In short, after reading the GTD book, I asked myself, "Why does the Purpose exist?" When you talk to a business owner and ask them why their business exists or how they came up with a purpose statement of "To help People do X," the business owner usually tells a story.
While it can vary across things, such a story probably sounds somewhat similar to this: "I talked to a friend / read a book / heard on the TV / etc. that something was going on and I realized that someone needed something. So, I sought to address that need and later realized I could make money off of it, too."
Various sources informed them about some state in the world (e.g. the context). This state revealed some market need that was not being addressed, and the person realized they could address that market need by creating such a business.

Moreover, I also asked, "Why does the purpose continue to exist? When will it no longer exist?" Some purposes can be fulfilled (i.e. planning a birthday party for a friend who is turning 24 years old). Some purposes can never be fulfilled. That's why businesses can still make money: humans will always need to eat food, so farmers will always exist; labor and materials aren't free, so people will pay them money to work for them and buy their produce.

As an example, many electronics retailer stores in America were doing just fine in one particular context: a world where the Internet wasn't used for shopping yet. Then, many went bankrupt after people changed their behavior (the context changed) and they bought things online. Many stores did not adjust to the newer context and went bankrupt as a result. However, one store in particular (Best Buy) did adjust and is still in business as a result.
When the context changed, it affected some things but not others. The general purpose did not change: people still needed electronics. However, the principles did: neglecting to compete with online stores in the correct way (whatever that was) led to a decrease in sales and eventually bankruptcy.

If one uses only the GTD methodology without these two additional steps, they can still be "unsuccessful" because their sight is still too narrow.

Edit: Also, keep in mind that this model is something I've been thinking about for a number of years, but one that I haven't fully formalized into something where all the hidden corners and "gotchas" have been found. In short, there's still bugs to fix in it. Think of it more as a useful framework to help guide your thoughts rather than a strict thing to adhere to all the time.

[JordanMartinez]

After reading through this again, I think there was a misunderstanding on my side. This PR currently lists the problems, and I implicitly read that as "therefore fix these things" which sounds like proposing a solution. I think this is incorrect, however, because exploring strategies are how we solve problems and this PR doesn't include strategy exploration.

Yeah, I think that misinterpretation is partly because of the header and partly because I'm thinking of and writing down possible things we could do to fix the situation as I'm documenting the situation.

[JordanMartinez]

I've stated this in #55 as well, but I think we should just merge all of our current PRs into the base Context/Narrative PR and continue reviewing/evaluating from there.

I would merge them right now, but I feel like it would be disrespectful to you if I did that.

Also, everything below the horizontal line below was just my general outline of what to put in the document when I first starting writing it. I didn't mean for it to be considered when you were evaluating this PR. So please ignore it.

---

- Evaluate PureScript's documentation using that criteria
- Explain why PureScript's documentation is lacking and what is being 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 -

A few different audiences

• shared (things we should explain, no matter who reads this)
  • Why read this document (capture people's attention in less than 2 paragraphs)
  • What is good documentation for new learners? (defining our terminology and criteria)
  • How does PureScript fair in that regard? (use that criteria to judge PS' current documentation)
  • Why isn't it better? (explain the obstacles that prevent it from being better)
• new learners (address things new learners care about)
  • What should your expectations be when learning? (frustration arises when expectations are broken)
  • How are people currently trying to improve it? (explain current efforts that people can tag alongside of / help / give feedback on)
  • How can you help in this effort? (you are most motivated, so you'll drive the effort or help out in some situations)
• Documentation writers (address things they care about)
  • How do I write good documentation for new learners?
  • How do I write documentation that does not go out-of-date quickly?
  • How do I write maintainable documentation?
  • How should I bring awareness to my documentation efforts?
• PS core contributors (things they care about)
  • What processes could be automated to save you time / lower the maintenance cost?
  • Questions whose answers would be helpful for others to know
    • What 'qualifications', if any, would they prefer someone has before delegating a project to them?

Here's a quick overview of some of its benefits compared to other languages:

• PureScript provides certain guarantees by default that other web languages do not or cannot (e.g. JavaScript, TypeScript)
• PureScript is more powerful than similar alternatives (i.e. Elm)
• PureScript can be used to 'patch' existing code, enabling one to slowly migrate a large application to PureScript one component at a time (unlike Haskell's GHCJS).

[JordanMartinez]

Whoops! Sorry about the merge. I thought I was on a different branch. I wanted to see what the document would look like if I merged all the current PRs together and then moved a few things around.

I'll force push and update things.

[chexxor]

I agree we should merge everything into a single version of this document, then go from there.

As a reminder to myself later, I'd like to revisit this comment when doing that follow-up review: #53 (comment)

[chexxor]

I marked all the comments I opened here as resolved, so this should be good to merge.

[JordanMartinez]

Thanks. Merged.