Updating docs and adding F#

[Fxplorer]

I am going through the docs like getting started and some of the control tutorials and finding them to be confusing sometimes. I should be considered a newbie in most aspects. I have managed to get docusaurus running local and I am going to submit some updates. The version says "Version: 11.0.0" which we are like 11.0.9. Should I assume to change docs in place for 11.0.0 or should the updates be made to the current dot version?

Second, I am trying to learn Avalonia, so I am doing things through C# first (which I know even less of than F#). If I apply these concepts into the F# templates, I am considering modifying the docs to show the F# code. In a similar way the MS docs on their site where the code samples default to C#, but have tabs for F# (sometimes, should be more) but also have a dropdown in the same way the docs version dropdown works. So if i select F#, then the code sample default to F# if they are there. Not sure how this works with docusaurus yet, but I want the node of OK if that seems like something that would get accepted, specifically:

Adding option to see code examples in F# (probably through tabs like the VS,Rider,CLI tabs work)?

[stevemonaco]

Docs already support Tabs / TabItem through a theming component. See https://docs.avaloniaui.net/docs/basics/user-interface/building-layouts/panels-overview near the bottom.

IMO, docs do need an overhaul on the sidebar for discoverability. It's a bit unclear how that should be handled. There are several maintenance steps here in general that will take several days of work, probably. Might be some new features in Docusaurus 3 that we should migrate to as well. I haven't read the release notes.

It's been discussed that we want more C#-based examples, partially because devs get the impression that XAML is required. I'll leave the F# decision to the maintainers. I assumed most F# devs using Avalonia were using FuncUI which has its own documentation.

[Fxplorer]

I noticed the tabs options when I was working on updating the Visual Studio Getting Started page. Thank you.

After rounds of exploration and trial and errors I have the following understandings of Avalonia:

• The basic avalonia.app template can work fine. The templates can produce axaml and C# or F#
• The IDE extensions do not give that basic option. Instead, they offer ReactiveUI or Community MVVM options.
  • deciding which to use is really based on personal preferrence in how to do things programmically
• There is essentially no examples anywhere of doing C# Avalonia without xaml
• The templates allow using F# and axaml and still using the MVVM paradigm
• FuncUI is probably the best method of moving to more traditional F# paradigms
  • Can use MVU paradigm here also (with or with out Elmish)
• The basic idea is that:
  • one needs to get things that happen when the Avalonia app is running (button clicks, entered text, etc)
  • change or update (or add maybe) things from code/logic
  • have application STATE somewhere, which can be a ViewModel or Elmish model(State) or in the controls themselves, etc.
• Avalonia is running in UI loop (single threaded). When something happens/needs to happen, one needs to decide to handle in the UI thread or pass it off somewhere else and be able to tell the UI thread things, hence where the MVVM or ReactiveUI come into play.
• While much is based on MainWindow, this is because of the WPF roots and the long history of Avalonia targeting desktop. The introduction of android/ios/wasm brought the MainView in which is just a control set into MainWindow on Desktop apps. If one then does everything in that top control instead of window, one is good.

Mapping between C# and the axaml and what FuncUI is doing can make doing things in F# is quite challenging, at least for someone not truly knowledgeable in any of it (or app development). Having the examples in F# would have sped up what I understand above by a lot.

So my question is if I started putting tabs in that showed the C# code in F#, or other F# information, will those PRs get accepted?

I just do not want to do the effort if that is not desired by the Avalonia team.

I realize F#ers are few, but that is partly because it is so hard to find reference and examples.

Of all the research I have done over the last 15 years, Avalonia is the most exciting and closest to the Golden Ticket I have encountered.

[stevemonaco]

IMO, this is a no, but I can't make that decision. The following points are my reasoning:

1. Lack of resources for maintaining docs in general. There are numerous undocumented features still waiting docs from v11.1, v11.0, and even before.
2. The doc examples will inevitably be piecemeal with F# examples, especially if we need F# examples for XAML, too.
3. The F# idiomatic way is to use FuncUI and we shouldn't directly couple every doc to an external library. There's less value if F# devs need to migrate F# examples to FuncUI. FuncUI has their own docs.

I would support a major docs section for non-XAML that explains how to use Avalonia without XAML in some targeted use cases. We need this for C# as well because many beginners believe Avalonia must use XAML. Some F# section for getting started / test drive would be good, too. Whereas the truth is that XAML is broadly preferred by developers because it makes creating UI hierarchies simpler and separates concerns, even if it's verbose.

@maxkatz6 Thoughts on accepting F# samples in docs?