How friendly can Roc be? · ideas

I've been thinking about use cases for Roc and started going down the path of mapping out what kinds of people may see Roc code. So far I've thought about Core Devs, Academics (research/teaching), Application Devs, Platform Devs, Students (STEM/others), Designers (UI/UX/architecture) , Analysts (data/business/commercial) etc. There is a bit of a spectrum on a technical scale from hardcore specialists through to general users.

Do you think Roc could become so Friendly that it is accessible to even the most general users? How is this primarily going to be achieved? Is this using the roc edit or would there be another tool using the Roc language as a plugin, or the editor as an engine, to provide a familiar graphical user interface environment with drag-and-drop boxes?

To explore this question I started writing up some Roc code in the future. I imagine a business analyst has been asked to update the email address for invoice processing or a similar task. They log into the companies IT system, find the relevant process and make the change ready for review by a supervisor. Below is a sample of what they might see if they looked at the Roc code for this function.

app "convert-invoices"
    packages { pf: "corpX-platform/main.roc" }
    imports [
        pf.GUI.{ App },
        pf.Email.{ Email},
        pf.SMS.{ Message },
        pf.Invoices.{ Invoice },
        pf.Cloud.{ Cloud },
    ]
    provides [main] to pf

main : Configuration
main =

    # Get files from a folder
    files <- await App.openFolderDialog {fileTypes : [".xlsx"]}

    # Convert them into invoices
    invoices <- files
        |> Invoice.convertFromFile
        |> Task.onFail \error -> Email.send {
                to: "buggy-invoices@corpx.org",
                subject: (Invoice.subjectFromErrorMessage error),
                data: (Invoice.dataFromErrorMessage error)
                }
        |> Task.await

    # Load them into the cloud and send a sms when completed
    invoices
    |> Task.map Cloud.loadInvoice
    |> Task.map Message.sendSMS

Brendan Hansknecht (Oct 19 2022 at 05:12):

Yeah, that looks reasonable. Though it really is the high level mapping rather than the real Roc code, if that makes sense. Like that code is the imperative driver code that makes the Task. Most likely, in any significantly sized system, devs would live heavily in purely Roc functions that probably don't use Task at all. They may just being deal with Roc types and truly pure functions. Though of course it will be mixed depending on how much they do io.

Brendan Hansknecht (Oct 19 2022 at 05:18):

Most of the Roc code changes would likely be pretty minor based on our current plans. Platforms will likely be urls, we have some changes planned around imports, await App.openFolderDialog {fileTypes : [".xlsx"]} should probably be files <- App.openFolderDialog {fileTypes : [".xlsx"]} |> Task.await. Also, if wanted a lot of the Task. prefixes could go away in favor of imports Task.await -> await.

But again, these are all just minor things and don't really change much of what the overall feel/look would be.

Brendan Hansknecht (Oct 19 2022 at 05:21):

Also, I would assume some of the imported libaries like Invoices would not come from the platform and would instead be app libraries, but again, that doesn't really change friendliness.

I guess one clear note on friendliness, a main function that uses Effects and Task and things of that nature is probably one of the least new user friendly parts of Roc code. It simply tends to have more syntax and constructs that a user must know about than pure functions.

Anton (Oct 19 2022 at 07:33):

I think we want to be friendly enough so that people can learn to program for the first time in roc. The editor will be a key tool in guiding new users. I think that roc can have a nice learning curve, allowing to start with pure functions and no type annotations.

Visualization of (the execution of) roc code and easy plugin development are also important goals of the editor that I expect will be useful to beginning programmers.

Helping people who only have experience "programming" with something like excel to understand and make changes to a large codebase is a tall order. I had not yet considered that, do you have any ideas in this area @Luke Boswell?

Luke Boswell (Oct 19 2022 at 22:41):

I have some ideas, I'll try and put something down in a longer form. I'll link it here in Zulip, although I apologise in advance if it is a bit rough. From my experience with Elm I believe that being friendly to general users is very achievable, and from what I see Roc already has good foundations. I'm most interested in the longer term UX in this direction. Having an integrated toolset opens up a lot of possibilities, so I'm interested to come at this from the top-down.

Luke Boswell (Oct 20 2022 at 06:11):

I have taken liberal inspiration from elm, and rust which I think have focussed a lot on their experience for new and experienced developers. Below is a possible direction that I think wraps a few ideas I have when I imagine Roc being Friendly. I am particularly excited by the possibilities of a projectional editor! To keep things short I skip over a lot of detail, please let me know if you want me to expand on anything. I may have gotten a bit carried away while writing this...

I think the roc binary should have built-in documentation and a tutorial that guides you and introduces you to both the Roc language and toolset. Something like a Rust book or Elm guide, blended with a programming environment like Try Elm or the w3schools Try It Yourself modules in a notebook format. I think the most logical place is for this to be integrated into the editor as a first class concept; rather than delegated to a website as this enables deep integration with other tools like formatter, package manager, etc and makes it easy to access and use. This would simplify the Roc getting-started to; Hey download and install this binary; start-up the editor; and have fun!

I think the, let’s call it, the “Docutorial” (not a serious suggestion), will provide both documentation and tutorial for Roc. It aims to support those new to programming, and those with more experience. How does it achieve this? The content is designed for both breadth and depth. This enables a confident programmer to hit just the wavetops or information they are looking for (i.e. a documentation use case); where a less experienced programmer might delve into a topic with interactive examples (i.e. a tutorial use case).

Navigating is conceptually similar to popular presentation tools that can navigate left-right and down-up. Down is progressing through a topic around use-case; while Right is moving on to the next topic. The table of contents or index is easily navigated using the keyboard, and resembles a cheat-sheet which summarises common editor controls and core language features. The Left-Right dimension changes the topic. Each topic presents a single use-case for example Working with Roc Numberics, or Working with Roc Types; and increase in complexity to advanced topics such as Visualising a Roc Runtime, or Developing a Roc Platform. The Up-Down dimension provides increasingly more depth in that topic; it may start with a simple overview and examples; it then expands with further detailed information such as links to reference material, explanations, examples, and quizzes.

At least some of this content should be bundled so that it works offline. Perhaps at least the content that would be necessary to get a beginner started, and the content covering the standard library. It won’t be possible to include all the available content; particularly as Roc will support multiple languages for the tutorial and documentation. So the package manager is used as a first class concept; it provides the functionality for users to search for published notebook apps. The core tutorial content may be maintained by core developers in the github repository, however more advanced topics are maintained by the community. Using the search functionality you can discover other notebooks that are publicly available online such as a roc-awesome, or a specific scientific paper.

The editor is excellent for storytelling; it provides the core functionality to express ideas through code, words, images, sounds etc. For example, editing content is as simple as writing code and markdown. When reading code examples the code is displayed using Roc’s syntax highlighting and formatting. Using plugins the code output could also be producing an interactive or animated chart. Changing to edit mode you can simply modify the underlying code and it will hot-reload and re-run the example. The text content, however, is rendered and displayed to the user in read mode. In edit mode the user is able to modify the text as it is a familiar markdown; with added functionality provided by plugins for other things such as maths equations or svg images. The plugins are written in native Roc code; and users are encouraged to drill into the underlying code, or write their own plugin as they explore Roc further.

Roc is a Friendly language because all of the tools; the editor, package manager, tutorial, REPL etc, are aligned to support the user from their very first experience.

Anton (Oct 21 2022 at 15:34):

Some excellent ideas here, thanks @Luke Boswell!
One thing I would change is that truly new programmers do need a different docutorial, because I believe it would need to go deep into "simple" things. But it is a good goal to allow this kind of exploration into depth aimed at those with very different amounts of experience.

Stream: ideas

Topic: How friendly can Roc be?