search

chexxor / purescript-documentation-discussion

A place to organize the planning of improvements to the PureScript documentation.
7 stars 0 forks source link

Why docs are lacking #53

Closed JordanMartinez closed 5 years ago

JordanMartinez commented 5 years ago

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

JordanMartinez commented 5 years ago

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

chexxor commented 5 years ago

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 notifications@github.com wrote:

@JordanMartinez commented on this pull request.

In 02-Context-or-Narrative/State-of-PureScript-Documentation-2019.md https://github.com/chexxor/purescript-documentation-discussion/pull/53#discussion_r263109802 :

+ +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 https://github.com/chexxor/purescript-documentation-discussion/pull/53#discussion_r263109802, or mute the thread https://github.com/notifications/unsubscribe-auth/AAzdmRA-ugWrrenHaRugQVKamhkk3T1Hks5vUB24gaJpZM4basaI .

JordanMartinez commented 5 years ago

I've worked on this some more today and I think this PR is ready for review.

JordanMartinez commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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)

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

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

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

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 commented 5 years ago

@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: https://github.com/chexxor/purescript-documentation-discussion/issues/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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

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

JordanMartinez commented 5 years ago

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 commented 5 years ago

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: https://github.com/chexxor/purescript-documentation-discussion/pull/53#issuecomment-473141227

chexxor commented 5 years ago

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

JordanMartinez commented 5 years ago

Thanks. Merged.