A plea for more documentation

[DavidThielen]

Hi;

I know documentation is a really hard problem that seems never ending. And having been CEO of a software company I understand why it's never going to be complete. And... I do think the documentation that exists is well written (98% of the time) and generally complete.

But with that, there's a dire need for documentation on issues where there is presently silence. The specifics I've hit recently (all Blazor server):

1. There's lots of examples of how to set up localization in the app. But nothing explains how it works. So it's basically write the code in the examples and then hope you get what you're expecting. There should be a page explaining how localization works and how to override it.
2. There are a lot of people that assume calling Task.Yield() in OnInitializedAsync() will then let you access @ref variables. What we need is guidance here. An authoritative answer of either this will always work or very bad idea. Either answer is fine, but let us know. Especially as, if it's a bad idea and will fail in the future, we're going to see a lot of web sites die on an update that does this.
3. How are we supposed to handle validating controls in forms. Both for complex properties and for validation that requires async calls (is a username on register unique). If the best approach means we have a bit of work on our hands, so be it. If ObjectGraphDataAnnotationsValidator is buggy and never going to be part of a release, so be it. But please, a web page telling us how to handle validation for use cases beyond the simplistic.

For the above cases, and I'm assuming similar questions, we're asking what approach to take so our code will work not just now, but in future versions. Because with all of us guessing, you know a fair amount of the code being written today will break in a future release. Or even worse, some bad practice has become so widespread, you have to support it which constrains future versions.

To reiterate, I think Blazor is a very well designed and implemented system as well as rock solid.

thanks - dave

[gfoidl]

@danmoseley should this be moved to https://github.com/dotnet/AspNetCore.Docs? Or please route it to where it belonds.