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
  • Tracking - Docs - code examples for all members, functions and types in FSharp.Core fsharp#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

• Language guide is not organized Organize F# language guide toc/index, add F# scenarios #26804
• Document primary scenarios (web development, machine learning, azure) Organize F# language guide toc/index, add F# scenarios #26804

[dsyme]

cc @cartermp and @baronfel for thoughts

[texastoland]

A few (possibly outdated) Language Guide issues I remember from fsharp/fslang-suggestions#523 (comment):

• 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 Collapse member val to member 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).