I couldn't find any user documentation for sandbox users (as opposed to programmers deploying builds of this code)

[aleith]

I can't write code to support this project, much as I would like to have those skills, I don't. What I could do is provide some kind of simple User Guide that could be linked to in the toolbar with a Help button or similar.

Content ideas (for e.g.) :

1. explain how to make adjustments to the code editor appearance and exactly what various pulldown menus and buttons do.
2. what the code editor engine is being used,
3. link to the Ace Editor GitHub repository,
4. some handy shortcuts for Save and Run
5. some tips (e.g. don't hit Cmd + R to run your code, it will not send a "Run" command, it will revert you code back to the last saved version — and that might have been an hour ago — I learnt this the hard way.

Without an installed GHCi on my desktop ATM I decided to try using this instead, I'd like to support in any (minor) way I can.

N.b. not sure if this is the place to address this issue or it's some other place, feel free to redirect me elsewhere.

[tomsmeding]

I think that would be useful! The functionality of the playground is intentionally limited (but does one thing well -- or at least, that's the idea), so I would hope that a help page would be pleasantly short. Perhaps the "Open source: GitHub" part at the right-hand side of the toolbar could be "Help | Open source: GitHub", where "Help" is a link that opens a modal with some text. Or do you think a separate page would be better?

1. I'm not sure there is too much to adjust, actually. As the implementer I have some configuration I can set on the editor, but there's little the user can configure as far as I'm aware. The whole website, including the editor, does switch between light and dark modes in the standard fashion, i.e. following whatever the browser thinks the user prefers.
2. Yep sounds good; in particular, the list of keyboard shortcuts is probably of interest to link directly.
3. ^
4. There's only one keyboard shortcut, currently: ctrl-enter / cmd-enter to repeat the last run-like action (run/core/asm). This is also noted in the tooltip for those buttons. I had trouble deciding on 3 good shortcuts (especially since a whole bunch are taken by ace, and the browser takes all the rest), so I just chose one.
   Regarding Save: I'm not sure this needs a keyboard shortcut. All saved snippets are currently saved indefinitely; the intended functionality is as an enhanced pastebin, not as an editor where you repeatedly save your code in order to not lose it. I think a keyboard shortcut for Save would suggest that it is natural to save often, which is not the intent.
5. Fair! Though that can perhaps also be alleviated by asking the browser to show a popup asking whether you really want to leave the page. (You will have seen this on other websites; this is standard browser functionality.) Actually, this is probably a good idea if the current code is different from what was saved. Let's see if I can implement this quickly.

[tomsmeding]

Let's see if I can implement this quickly.

Done. :) Currently the dialog is always shown if you've changed the file; if you happen to arrive back at the original code, e.g. by undo'ing, the dialog is still shown. I guess this is not too bad, since you are losing information -- your undo history.

[aleith]

Firstly, I think the playground is an excellent resource and with people complaining about Haskell's limitations or frustrations due to a lack of user friendly/state-of-the-art tooling, well this playground isn't exactly developer tooling per se but it does improve accessibility for people wanting to demo some code for those without GHCi installed.

It was watching a training video someone live streamed for me that I saw this tool, he used it to demo the code throughout his demo. worked well.

1.a. I just noticed the difference in appearance in code colouring turned out that was just me in a dark mode and him (and my phone 12 hours later) seeing the code in a light mode.

1.b. On the point of legibility, you may not be able to change this, but I think the bold typeface used in the light code mode is way too heavy for legibility, least on my macOS and iPhone screens. If it's possible to substitute that font for a lighter weight in the same font (say a medium instead of bold or whatever) I'd recommend that. Or swap out the font family if necessary, there are hundreds of type families that are unrestricted for use online and more suited to reading and writing code. Maybe this is an issue to be directed to the text engine developers. (I'ma. designer by trade so I notice things like this perhaps are than others would)

2. . I wanted to find the shortcut for comment toggling on blocks of code. I swear I tried ⌘ + "/" but I must not have because I just looked it up and tried again that's what it turns out to be on macOS! so yeah linking to that would be awesome, many people would be unaware so many commands have keyboard equivalents (and playground has no tool menus to access them or discover them in, making shortcut discover via help even more important IMHO)

3. yes please link to that page on Ace more directly in your own help page, when I got to the GitHub page for Playground I was a bit disappointed to have to start trawling to try and find some user level help (as opposed to those who want to deploy this to a server).

4. I managed to discover the run shortcut by intuition! thanks for adding it. I did wonder about how long you preserve the code people have "saved" before trashing the file, or perhaps you just have a directory allocation and start removing when it hits a threshold in MB. Fine not to have a save I there is a safe way back, I couldn't recover my code at the time. I guess it's like using Disqus, all comments should be writing in some other tool and copied over if its more then 5 or 10 minutes of work.

5. Great, that will protect from lost code in 99% of cases I would think.

[tomsmeding]

About saving: there is also the possibility of regularly saving your current code in your browser's LocalStorage -- essentially a little database in the browser's files where every website has its own section where it can store some data. The upside of doing so would be that if you close the playground and then later open it again, your code will still be there -- usually. The downsides are that 1. if you clear "site data" in your browser (and some browsers do this automatically, be it at the user's request or not), the code will be gone (which would be unexpected), and 2. it's local on your device, so if you move to a different computer (or a different browser on the same device), your code won't be there.

I think it's better to not save your code to LocalStorage because doing so would give false impressions of durability of that stored code, and not storing it at all is at least an easily understandable mechanic. What do you think? (Now that I have a user to talk with :) )

On the point of legibility, you may not be able to change this, but I think the bold typeface used in the light code mode is way too heavy for legibility, least on my macOS and iPhone screens.

I'm just using stock the github theme from Ace in light mode and monokai in dark mode; you can try out all the built-in themes here: https://ace.c9.io/build/kitchen-sink.html
It wouldn't be terribly hard to make a custom theme (it's just CSS), but it's even easier if one of the stock the themes works. :)

[tomsmeding]

A preliminary help dialog is now live on https://play.haskell.org. It doesn't work properly on mobile yet.