Async Articles - Proposal for Change

[cartermp]

The original async docs were written with a differentiation on the async model for each language. C# and VB share the same model, so there were two documents: one for F#, and one for C#/VB.

The new TOC doesn't have a good way for these docs to fit in as-is. The new TOC has the C#/VB document shaved of all VB content (of which there was very little) in an effort to get something available. Here's what I'm thinking:

1. Create a language-agnostic document containing much of the detail that the current C# doc has (ex: all the Task details), and link to that document from the current C# doc. This can live outside of the TOC for now.
2. Augment the current C# doc to have a few more code samples (ex: using Task.WhenAll()) and get most of the details about the model out of the doc. The focus would shift to be fully "how do I write async code in C#" rather than explaining that and the async model.
3. Create a VB doc which links to the language-agnostic doc from above. It would be pretty much the same doc as the C# one. It would currently live outside of the TOC temporarily as we figure out how we're going to incorporate F# and VB into the TOC.
4. Keep the current F# doc outside of the TOC as well.

When we have a good plan in place for how we're going to represent VB and F# in the TOC, the VB and F# async docs would live in those sections.

/cc @blackdwarf @richlander @BethMassi

[BethMassi]

That sounds like a good approach to me.

[stevehoag]

Yes, makes sense.