Welcome to fsharp-core-docs Discussions!

[dsyme]

👋 Welcome!

We’re using Discussions as a place to connect with other members of our community. We hope that you:

• Ask questions you’re wondering about.
• Share ideas.
• Engage with other community members.
• Welcome others and are open-minded. Remember that this is a community we
  build together 💪.

To get started, comment below with an introduction of yourself and tell us about what you do with this community.

[pbachmann]

Hello and thanks for the welcome. I am a long-time VB/C++/C# developer who avoids corporate work in the belief that the priority for software development at the moment is to bring new ideas to life not just computerise old ideas.

I have worked with F# for about a year after finding C# got in the way of my designs. I honestly didn’t want to throw years of familiarity with C# out of the window and tried my best with C#, making use of all of its latest features (records, switch expressions etc.). Ultimately, I found them to be unnatural appendages to the already ungainly object orientated model.

I appreciate how F#, by contrast, makes simple things simple. If I make a function call where the response might be choice between a person’s details, or a communication failure, or a general error with an explanatory text, then F# makes that easy to express.

My purpose here in this forum is to help, where possible, to make F# better understood, especially by newcomers like me.

I have done some experiments with regard to the above but thought before I foist them on to the community, it might be prudent to look at what directions are already being pursued. Accordingly, I read a lot of material including:

dotnet/docs#26813
dotnet/docs#26727
https://mobile.twitter.com/dsymetweets/status/1454226430758465538
dotnet/docs#26804

In general, the links above seem to be about improving the documentation in conventional ways.

There are two problems I have with that:

• The documentation is already very good.
• No one reads documentation anyway.

To illustrate the second point, if you type “F# computation expressions” into Google or Bing, the first page that is displayed contains a long source code example that, for five and half years, did not compile. There is no shame in making mistakes, of course, but the fact that no-one complained in all that time strongly suggests people have little patience with documentation.

So what to do instead of improving existing documentation? I suggest:

1. Making F# Intellisense the best in the business.
2. Introducing F# Pearls.

Since this forum is focused on documentation, I’ll just talk about an idea I've invented called F# Pearls.

F# Pearls

Just as a pearl is special, F# Pearls are pieces of documentation with special qualities. Pearls are:

• Brief (less than a page)
• Simple
• Practical
• Self-contained
• Focused on a single subject
• Intelligible by people with no background in F#
• Honest (do not try to cover over seemingly awkward aspects of F#)

The subject of each Pearl should:

• Be important (something you need to know to program in F#).
• Probably not be obvious to people new to F#.
• Have one or more (but not be overburdened by) practical suggestions as to how to deal with situations highlighted by the Pearl.

A completed Pearl is added to the list of Pearls, which is ordered by importance. The list should appear as one long Html page with a table of contents at the top, allowing readers to skip to a topic of interest or to read through all the Pearls.

The main purpose of F# Pearls is to turn people wanting to learn F# into working developers, but there are many other benefits:

• Since a Pearl is small and self-contained, everyone should feel empowered to contribute one. Once they have contributed one, they may feel emboldened to contribute another one.
• People writing Pearls will learn about F# in the process.
• Understanding a Pearl gives the reader a sense of achievement that reading the seventeenth page of a fifty-eight page article does not.
• It sends a message that F# is a language for people who like simplicity.
• Each attempt at explaining F#’s unique way of doing things is an opportunity to extol the benefits of that approach (eg. the single pass compiler means the main code always appears at the end of a function).
• Where there is no particularly good reason for F#’s unusual way of doing things, at least the newcomer will feel better about themselves knowing it’s not their fault for not immediately understanding.
• The Pearl may uncover something that that needs to be developed further and can link to this further work (an exception to the rule that a Pearl should be self-contained).
• Pearls are fun – because by definition they are about insight and revelation. There is a little “Ah -ha!” in every one.
• People’s complaints (eg. frustrations with understanding indentation rules) can get turned into Pearls.

Sample Pearls

Example 1: F# decides the type of list/array by looking at the first element

Some programming languages scan entire array literals trying to guess what sort of array it is, or alternatively, insist that the type is stated explicitly. F# takes a simpler approach and uses just the first element to indicate the type of array.

For example, the string at the start of the following list makes this a list of strings. You will get an error when the compiler encounters the number 1:

["a";1;2;3;4;5]

To make this list compile, you could make it an object list by casting the first element to a .Net System.Object as follows:

["a" :> obj;1;2;3;4;5]

Example 2: Don’t despair over F# collection function names

There are over 100 standard functions for processing lists, arrays and sequences etc. These functions have the format:

[module].[functionName]

For reading and writing F# code, you are encouraged to learn all these functions. But how? The names themselves do not help much. For starters, the module names have limited meaning, usually just referring to the specific type of collection being targetted (List, Array and Seq etc). The function names often do not adequately communicate what they do. For example, it is unclear how List.pick and List.choose are different.

There are better ways to learn the huge number of functions than to memorise them all. You can use modules [link to sample modules], or write your own, that map to the standard functions with functions that have more useful names. A more useful name might prompt you for what you’ve got and (roughly) what you want. So, a module might have entries like these:

type List_one.pick = List.pick

So, in the case where you’ve got a List and you’d like to end up with something that represents one item in that list, you type List_one. and intellisense will prompt you with names such as pick, find, findBack, exactlyOne etc.

Immediately, you are prompted with all the functions that take a list and return something that represents one item from that list. You’ve narrowed the scope from learning 100 functions to choosing from a few.

[pbachmann]

I'm disappointed that there has been no response yet; these F# Pearls seem like an excellent idea. Perhaps the unfamiliarity of a new concept has put people off? Maybe it would help people to think of pearls merely as small, self-contained beginners' tips?

In the last couple of weeks, I've stumbled upon more situations that would benefit from having their own pearls:

• Indentation - I was stuck for 30 mins because the compiler didn't tell me that indentation was the problem, instead it told me I was missing something or other. What simple rules to follow for people used to curly braces?
• How to help Intellisense do its job by providing it with enough code for it to infer your types?
• Imperative looping must be sub-optimal or there'd be less reason to move to F#. So why is it bad and what are the definitive alternatives?

In relation to the last point, Scott Wlaschin wrote a couple of posts some years ago:
https://fsharpforfunandprofit.com/posts/control-flow-expressions/
https://fsharpforfunandprofit.com/posts/conciseness-extracting-boilerplate/

... but they are too long by Pearl standards, and do not mention the rec keyword which, I would have thought, is essential in describing alternatives to loops.

[dsyme]

Hello @pbachmann

It's a fundamentally great idea.

For discussion this may not be the best place - this is really a technical repo for delivering doc content authored in dotnet/fsharp. It might be better to move to fslang-suggestions, and also to post links to the discussion on twitter.

For execution, I'd just say "go for it" - just like Scott Wlaschin did (no permission was asked or needed to create "F# for fun and profit") . That is, create a blog, and start creating content, and perhaps find some like minded people on twitter or elsewhere to co-contribute. I and others will amplify.

All your suggestions for topics to cover are good.

[pbachmann]

Thanks @dsyme for the feedback.

I had not envisaged starting and maintaining a new project myself for what is really a side interest, but nevertheless can see why an idea should be shown to work before it might (if ever) be the sort of thing that gets included in official documentation.

Re Implementation: While I see some value in the blog approach, I imagined a collaborative effort rather than one person preaching through a blog.

I could post questions and answers on StackOverflow.com, which is a collaborative platform, but that platform seems to be about getting people out of trouble, whereas what I propose is more in the spirit of avoiding trouble in the first place.

I guess I could create a new site that allows contributions within a Pearl-type framework. That's something for me to explore.

Re Finding like-minded people. That's an interesting challenge. One might arbitrarily divide F# programmers into two sorts: experts and non-experts.

An expert may know 10 key facts about, say, indentation rules that apply to F#. Saying to such a person, "Just give me, in simple terms, no more than three of the most important rules, and then shut up" might hurt his feelings. What's the use of knowing 10 key facts and only being able to express 3 of them? He may say, "I must tell you all the facts because they are all important!" I would say to the expert in this case that he should go back to drawing board and rearrange the facts to see if 3 key principles can be designed. The expert may rail against this too, feeling that you're turning him from a expert who knows it all into some little learner.

The situation with the non-experts is interesting too because they are likely to be shy, fearing their ignorance will be put on display and they might be pounced on by an expert. This is a real shame because if people feel their insights do not matter, they may become passive. Giving non-experts permission to put forward preliminary views might make sense. One might use Edward de Bono's notion of a "proto-truth", in which he suggested:

"In place of absolute truth there is something called ‘proto-truth’ which is usable but improvable." - (The Happiness Purpose (p. 27). Kindle Edition).

So the idea would be to encourage non-experts to fearlessly offer ideas on F# indentation as long as they accepted that these were merely stepping stones to better ideas.

While there are challenges, I see big rewards.

Thanks for the direction and encouragement.