Revisit tweaks PR

[bartelink]

I was hoping https://github.com/fsprojects/fsharp-cheatsheet/pull/12 would get debated and merged.

Would love to see someone redo most of the stuff in there, perhaps as a few easier to review/merge PRs (now we've had #18, it probably becomes much smaller too).

[charlesroddie]

I was going to do some edits along the following lines:

• Removals: inheriting from classes, single-case discriminated unions, downcasting, -> in sequence comprehensions.
• Reductions: exceptions (reduce complexity of example), active patterns (e.g. removing single-case active patterns)
• Additions: string interpolation, the ||> operator, computation expresions (async, with mention of result)
• Alterations: string functions like printfn replaced with interpolated strings where appropriate, pattern matching focusing more on DUs, record augmentations moved out of the records section to type augmentations
• Appendix or remove: compiler directives, range operator

Could do this as a PR here (which might or might not get accepted) or keep a fork.

I believe the cheatsheet can eventually be on one sheet!

[bartelink]

I agree in principle with pretty much all of the changes you've outlined. I think we'll be able to keep everyone happy in this repo; if necessary, the final page can be a TL;DR page and/or have 'and a few more things' appendinx @SpiralOSS if any of the above sounds like something you might have quibbles with, best to flag now so Charles can focus on the stuff that should be a quick uncontentious merge without much to/fro necessary?

[SpiralOSS]

I believe the cheatsheet can eventually be on one sheet!

I think so too.

Removals: defining classes and then inheriting from them, single-case discriminated unions, downcasting, -> in sequence comprehensions.

Agreed.

Reductions: exceptions (reduce complexity of example), active patterns (e.g. removing single-case active patterns)

I have updates for exceptions coming. I didn't want to swamp @bartelink with PRs, but work also took off like a rocket. Let me get that in. (#20 )

Additions: string interpolation, the ||> operator, computation expresions (async, with mention of result) Alterations: string functions like printfn replaced with interpolated strings where appropriate, pattern matching focusing more on DUs, record augmentations moved out of the records section to type augmentations.

I have updates for string interpolation, but would love updates for the other items.

Appendix or remove: compiler directives, range operator

That makes sense.

[charlesroddie]

Note that if there if there is an intention to get this cheetsheet to a single sheet, then any line remaining will have at least medium importance, and any line added now will need to be compensated for - most likely by reverting the addition, or if not by deleting an existing medium-importance line. I am conscious that when I do a PR it will be very ruthless with additions.

In particular the section on exceptions should be much shorter than it was yesterday and much much shorter than it is today, and interpolated strings should be a two-line addition in my opinion (1 explanation, 1 example).

[bartelink]

I feel the first step is to address the open issues to get to a stable state (it'll be verbose, but there won't be too many outright bad/wrong examples, and/or outdated idioms).

If that gets done (and we have PDF generation), we're in a position to assess the target size, and how that might be achieved.

That'll allow us to decide what we're shooting for, i.e.

if we know we're at 1.5 pages, it's a big ask to get to 1. If we know we're at 2, maybe we just need to have a TL;DR page and an appendix page

I guess it boils down IMO to the fact that making the hard choices about what has to go and/or be aggressively edited should come after fixing things that are wrong regardless of the page count.

Also, while I think there's sufficient expertise at the table, it may also be worth getting some more eyes on it at the point where the obvious bad things have been removed. e.g. there might be folk that can be grabbed from fslang-suggestions or the Amplifying crew that might have good insight as to what's not worth it's space and/or a point of confusion.

Specifically re exceptions, in general I don't even use the exception mechanism - perhaps this is ignorance (have not looked at what code is generated and what goes), but e.g. conveying that there is no try/catch/finally construct can take some space.

[SpiralOSS]

Does it make sense to copy the fsharp-cheatsheet.md to fsharp-cheatsheet-long.md and then work on them independently? I'll keep adding to the long version and @charlesroddie can start trimming it down.

[bartelink]

TL;DR I think we should stick to one version for now. It's not yet proven that the world needs (or anyone is pushing for) two sibling cheatsheets.

---

Depends on progress/time available. I think a few days can close the issues list. And it'll be helpful for everyone to more or less agree with most things in it.

Once that's done, we can define a target.

My feeling is that a one pager should be viable, and could call out to footnotes - those footnotes can just all be on page 2. So we can e.g. have an exceptions section that shows the main keywords, and it can hint "and we also have 5 more examples"

While there might be one or two topics where there's a conflict between explaining vs summarising, on the whole, a well chosen example tends to be short anyway.

(While my preference would be for a TLDR page and an extras page structure, one can imagine doing multiple renderings from the same base. Either way, I'd really like to see the thing stay in one MD file so people can do their own custom versions and ctrl-F to search in it etc.)