C# tutorials - LINQ

[BethMassi]

We need LINQ in the tutorials list. This is a big topic so there could be a lot of samples here. Good starting point: https://code.msdn.microsoft.com/101-LINQ-Samples-3fb9811b

Tutorials should include one or more code examples, each example should also show expected output and should include an explanation of the code where it isn't obvious. Examples shouldn't be dependent on a specific IDE or target platform.

[BillWagner] Adding sub-tasks:

• Bring forward the LINQ overview from the .NET Primer.
• Provide an overview of LINQ and databases, with extensive links to the EF documentation
• Provide a reference to Azure Storage LINQ providers.
• Bring forward explanations from the 101 LINQ samples (code has been added, descriptions have not).

[matthewreily]

I'd like to help out on this one and will gladly divide an conquer with anyone else.

[BethMassi]

@matthewreily you rock!
@blackdwarf @cartermp how do you envision the C# tutorials land in the repo folder structure we have? Should we pile into docs/tutorials-samples/CSharp/LINQ ?

[blackdwarf]

Are these going to be done in restructured text or markdown?

[BethMassi]

I thought they had to be rst. That's what it says in the contributing guide 😄

[blackdwarf]

Ah, ok. So this is interesting. let's keep them where you suggested. Its the thing that makes most sense. The actual code for the tutorials I think should also be there.

[cartermp]

The existing LINQ article as some examples which could be shared/altered/used as a starting point for this.

What I'm hoping eventually happens is for any code snippets (be them in tutorials or elsewhere) are embedded directly from some code which sits in the repository, and is buildable. It would be a good idea to focus on the code snippets in that way now so that we don't have to retroactively go back to every document which uses LINQ and embed buildable code.

[blackdwarf]

Sure, rest has that option. It is more of where the said source code will sit, which repo? I suggest this one, for now, that is, co-located with the documents.

[BethMassi]

Cool. I think we should start with a quick overview page (pulling from the existing doc) and then further break the content down into folders based on the type of operation. @cartermp @blackdwarf is this how you want the samples, in its own folder next to the doc itself? How much should we spit down to? Is one sample per doc or one doc can have multiple samples?

docs/tutorials-samples/CSharp
/LINQ
overview.rst
/restriction-operators
/where-simple1
where-simple1.rst
/sample
/where-simple2
...
/projection-operators
/partitioning-operators
/ordering-operators
/grouping-operators
/set-operators
/conversion-operators
/element-operators
/generation-operators
/quantifiers
/aggregate-operators
/join-operators

[cartermp]

I actually like the idea of having a totally separate /samples structure that samples are pulled from. Co-location with docs could get tricky when docs from multiple, unrelated areas pull in example code from the same sample source. After that, I don't have an opinion on the structuring. Having a single file with multiple functions which each cover a piece of LINQ (e.g. WhereSample1()) would be the way I'd go about doing it, but multiple files is fine too.

@blackdwarf what are your thoughts on this?

[BethMassi]

Okay I like that proposal - we create a top level /samples folder next to the /docs and use a similar taxonomy for the folder structure under that. What's confusing is we have /tutorials-samples under docs right now. Should we rename to just /tutorials ?

How about this? @cartermp @blackdwarf @matthewreily

/docs
    /languages
        /csharp
            /linq
                overview.rst
                restriction-operators.rst
                projection-operators.rst
                partitioning-operators.rst
                ordering-operators.rst
                grouping-operators.rst
                set-operators.rst
                conversion-operators.rst
                element-operators.rst
                generation-operators.rst
                quantifiers.rst
                aggregate-operators.rst
                join-operators.rst
/samples
    /languages
        /csharp
            /linq
                /restriction-operators
                    where-sample1.cs
                    where-sample2.cs
                    where-sample3.cs
                /projection-operators
                    ...
                /partitioning-operators
                /ordering-operators
                /grouping-operators
                /set-operators
                /conversion-operators
                /element-operators
                /generation-operators
                /quantifiers
                /aggregate-operators
                /join-operators

[cartermp]

I agree that we should rename /tutorials-samples to tutorials under the docs folder. Let's go with that.

I think LINQ should be in its own area in the /samples directory because it's not tied to C#. Perhaps something like this would work well:

/samples
    /linq
        /csharp
            /restriction-operators
        /vb
            /restriction-operators

[blackdwarf]

So...how will this work for your proposal on building the samples with the actual code it is...sampling, so to speak @cartermp ? I'm fine with the overall approach. Renaming tutorials-samples to tutorials also makes sense.

[cartermp]

These samples would be built when a corefx library is published. So a hook would run a script which scans this /samples folder, restoring packages and rebuilding the projects. There would most likely be some sort of indicator in the README listing any samples which are broken and need to be updated.

At least that's what I'm thinking. This is assuming none of the samples rely on .NET Framework.

[BethMassi]

@cartermp WRT the samples structure, I think it would be helpful to have the same (or very close) taxonomy to the docs. So should it be:

/docs
    /linq
        overview.rst
        /csharp
            restriction-operators.rst
            ...
       /vb
            restriction-operators.rst
            ...

This means that VB & C# code would be separate in each of the tutorials. I think that's good, but we effectively double the number of docs.

[cartermp]

The linq tutorial could be written in a way that had side-by-side C# and VB samples. Something like this:

Filtering a list is easy!  Here's how you can do it.

C#:
var filtered = items.Where(item => condition(item));

VB:
Var filtered = items.Where(Function(item) condition(item))

The C# line of code would be embedded from the /csharp folder in /samples, and the VB line would be embedded from the /vb folder. The taxonomy wouldn't be exactly 1:1, but it would eliminate redundancy in the documentation. At least that's what I'm thinking.