F# docs planning

[dsyme]

This is a tracking issue for myself, @KathleenDollard and the F# community to track missing F# docs and other improvements we can make. Contributions are welcome

This is all about the docs at https://docs.microsoft.com/dotnet/fsharp/

Specific work items up-for-grabs

• Tutorials
  • [ ] string programming
  • [ ] regex programming
  • [ ] list programming
  • [ ] "Tour of F#" is weak and needs rejig
• Language guide
  • [ ] Indentation-aware syntax, have requested to add this content as a new page: https://fsharpforfunandprofit.com/posts/fsharp-syntax/
  • [ ] Using Dictionary
  • [ ] Add overview of .NET collections (Dictionary, List etc.)
  • [ ] Add overview of object programming
  • [ ] Add section on MailboxProcessor
• F# core library
  • [ ] https://github.com/dotnet/fsharp/issues/12124

• Tools

  • [ ] Visual Studio Enterprise code coverage is great but needs configuration, see https://docs.microsoft.com/en-us/visualstudio/test/customizing-code-coverage-analysis?view=vs-2022. Pardticularly need to add

  
     <Attribute>^System\.Runtime\.CompilerServices\.CompilerGeneratedAttribute</Attribute>

• Architecture guide
  • [ ] We can add an F# architecture guide under the .NET architecture guides here and here

Problems identified

• [ ] No tutorials on string processing, .NET types (strings, collections, web requests...) etc
• [ ] The "tour" uses long chunks of code with discursive text in comments. It is too long and not compelling.
• [ ] The language guide is half-guide, half-reference. We make it more "guide" while keeping the reference material
• [ ] Language guide is misssing some important overview sections like "object programming"
• [ ] Native interop using NativePtr is not covered
• [ ] Generic .NET material like https://docs.microsoft.com/dotnet/ contains very few F# references. We can update this.

Completed work items

• [x] Language guide is not organized #26804
• [x] Document primary scenarios (web development, machine learning, azure) #26804

[dsyme]

cc @cartermp and @baronfel for thoughts

[texastoland]

A few (possibly outdated) Language Guide issues I remember from https://github.com/fsharp/fslang-suggestions/issues/523#issuecomment-899012504:

• Add double and single types and replace usages of float and float32 with them.
• Add Type[] syntax and replace usages of Type array with it.
• Add note why Type[] declares an array (because C#) whereas [value] defines a list (because OCaml).
• Add an equivalence table inspired by my description in fsharp/fslang-suggestions#1062 to quickly look up and compare different property/method syntaxes.
• Add member _ syntax and (possibly?) replace usages of member this with it when this is unused.
• Add page comparing and contrasting Task vs Async (CC @Ryan-Palmer).