AOT-friendly documentation

[mtmk]

One thing I've been meaning to dive into is looking for gaps in documentation. PRs like this could include documentation that addresses cases such as folks wanting to remain AOT-friendly. Perhaps an article or some section in the docs.

Could also include documentation like you've mentioned about where the delineation is for projects that should be AOT-friendly. Either in CONTRIBUTING.md or the docs.

Originally posted by @rickdotnet in #607 (review)

[rickdotnet]

I thought there was already an issue about enhancing docs. I don't see it though, I started looking at the doc setup this morning. First time docfx'r.

Made it this far:

dotnet tool update -g docfx
git clone https://github.com/nats-io/nats.net.git
cd nats.net/docs
docfx docfx.json --serve

To expand on that comment, I think since AOT is a hot topic it should get a dedicated section that serves two purposes. One would be for users to have a quick understanding of which projects they might gravitate towards. But, also for developers to reference and understand the vision from the core team about how they should think about the project dependencies.

It's crucial that we avoid using non-AOT-friendly APIs, such as ad-hoc JSON serialization, in the core library.

[mtmk]

I thought there was already an issue about enhancing docs. I don't see it though

maybe this one #345

edit: btw I'm happy to merge this issue into #345 if you like

[rickdotnet]

Wth. My search must have been broken.

I think an AOT article is important to get out, so probably keep them separate. It's pretty buzzy and a frequent flyer in discussions. The other issue could maybe reflect the larger documentation review and collect known gaps. For example, serialization has been simplified. We could update the top of that article to give the happy path to new users, then provide more information for folks wanting to dive deeper.

[mtmk]

that makes sense. we can get an AOT page out first.