search

chexxor / purescript-documentation-discussion

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

New learners section #55

Closed JordanMartinez closed 5 years ago

JordanMartinez commented 5 years ago

Still a WIP, but I thought I'd get this branch started.

JordanMartinez commented 5 years ago

I don't know how to edit pictures like this, so that has me a bit concerned and feeling dis-empowered about that one piece of this document, but I like pictures so I invite it in.

Sorry about that. The program I linked to in the comment is what I use to create that diagram (and many of the other diagrams I've made in my learning repo). The picture is generated by exporting the file as PNG. So, I update the diagram via the program, save the diagram file (.graphml), export it as a PNG and overwrite the previous PNG file. Then I commit the changes to git.

JordanMartinez commented 5 years ago

Just wanted to file away some thoughts:

chexxor commented 5 years ago

https://github.com/chexxor/purescript-documentation-discussion/issues/57 I made this issue to inform readers of this how that diagram file is edited/maintained, btw.

chexxor commented 5 years ago

we should state that the sources we read seemed to think that PS is typically used for front-end things. If one needed backend stuff

I wonder why people have this idea, that PureScript is primarily used for front-end things... It is a general purpose language. It could be true that people prefer to choose PureScript because it's relatively easy and standard to quickly build a browser app, which makes a new programmer feel rewarded. Because of this, perhaps this is the reason people tend to use browser apps as the basis of their discussions.

I wonder how this aspect of PureScript and teaching should affect this project here. IIRC, this project is about making PureScript more accessible by improving its documentation and perhaps providing a narration of the learner experience which could help the maintainers of the PureScript tools when they make design decisions. If so, ensuring this doc page has a note which indicates this how new learners prefer to learn (by using browser UI apps as the teaching context?).

chexxor commented 5 years ago

I realize now that my above comment doesn't immediately apply to this PR. I'll look for a better place for that comment.

JordanMartinez commented 5 years ago

I think this is because of the node backend.

If you're using PureScript, you're usually looking for a better front end solution than JavaScript. Those who use it can be coming from other languages they are already familiar with. So those using Haskell will just use that. The same for others.

So most people who do develop libraries do it for the front end, not the back end.

JordanMartinez commented 5 years ago

we should state that the sources we read seemed to think that PS is typically used for front-end things. If one needed backend stuff, they'd usually use a more powerful FP language (Haskell) or a non-Node backend (e.g. Erlang, C/C++). There isn't a survey we've done to determine this, so this thought might be wrong.

Done.

JordanMartinez commented 5 years ago

Rather than evaluating learning resources, we might want to explain to new learners what their type is (similar to what we've already done elsewhere)

For this task, I'd like to just relocate the "Evaluating PureScript's documentation" section to be closer to the 'new learners: what is best way to learn purescript?' section. We can clean it up in a future PR.

JordanMartinez commented 5 years ago

I think our goal should be to merge all the current work we have into a single branch and then troubleshoot from there.

chexxor commented 5 years ago

Yeah we can merge this, I think.

JordanMartinez commented 5 years ago

Done!