Add documentation on cross-platform development options in .NET

[hach-que]

This adds documentation on available tools for cross-platform development in .NET. This is just based on the options that I am aware of.

(disclaimed: I am the developer of Protobuild)

[matthewreily]

Thank you for all the effort you put into this documentation @hach-que. Not sure that we are incorporating third party libraries as part of our core-docs at the moment. cc @BethMassi @cartermp

[cartermp]

AFAIK we aren't documenting third-party solutions with the doc set at this time. I haven't done an evaluation of the tools ... is this based on .NET Core?

[hach-que]

It's based on .NET in general and is intended on giving a comparison of the
different solutions for cross-platform .NET code and the pros / cons of
each.

On Mon, Dec 7, 2015, 06:22 Phillip Carter notifications@github.com wrote:

AFAIK we aren't documenting third-party solutions with the doc set at this
time. I haven't done an evaluation of the tools ... is this based on .NET
Core?

—
Reply to this email directly or view it on GitHub
#160 (comment).

[stevehoag]

In my opinion we should limit our docs to .NET Core. A comparison of cross-platform solutions seems out of scope here.

[hach-que]

It's odd that this repository is associated with https://dotnet.readthedocs.org/ then, because that subdomain implies documentation for all of .NET, not just .NET core (which is a specific subset). To be honest I feel as though that domain should be reserved for documentation that covers .NET in it's entirety, and that https://dotnetcore.readthedocs.org/ would be more appropriate for a subsection of the ecosystem.

[cartermp]

We're not using readthedocs anymore. Our new in-progress doc site is here: http://dotnet.github.io/docs/. The intention of these docs is to cover .NET Core, not .NET as a whole (Framework, Mono, etc).

Unfortunately, based on my understanding from reading the docs on Protobuild, it's an alternative project system that uses mono. I'm inclined to close this PR out because of that lack of alignment with the .NET Core platform.

You may want to consider adding Protobuild to this list of OSS .NET projects we maintain. It looks like a pretty cool system for building multi-targeted apps.

[hach-que]

Actually the only reason we're not targeting .NET core by default is
because it's not stable for all the desktop platforms yet. There is the
intention to change the default in Protobuild once that happens:
https://github.com/hach-que/Protobuild/issues/87

But you are correct in that running Protobuild uses Mono on Mac or Linux to
actually run itself, this is again because CoreCLR isn't shipping in most
places (like Linux distros through the Xamarin repositories).

I will submit a request to have it included on
https://github.com/Microsoft/dotnet/blob/master/dotnet-developer-projects.md
(actually I submitted the project for inclusion in the .NET Foundation a
week or two ago, but I haven't heard back yet).

If you're not using the dotnet subdomain on read the docs, could you free
it up so someone else can use it? I still think it's valuable to have
documentation that covers the entire ecosystem (all the frameworks and how
they fit together), in addition to the .NET Core docs.

On Thu, Dec 10, 2015, 10:52 Phillip Carter notifications@github.com wrote:

We're not using readthedocs anymore. Our new in-progress doc site is here:
http://dotnet.github.io/docs/. The intention of these docs is to cover
.NET Core, not .NET as a whole (Framework, Mono, etc).

Unfortunately, based on my understanding from reading the docs on
Protobuild, it's an alternative project system that uses mono. I'm inclined
to close this PR out because of that lack of alignment with the .NET Core
platform.

You may want to consider adding Protobuild to this list of OSS .NET
projects
https://github.com/Microsoft/dotnet/blob/master/dotnet-developer-projects.md
we maintain. It looks like a pretty cool system for building multi-targeted
apps.

—
Reply to this email directly or view it on GitHub
#160 (comment).

[BethMassi]

@hach-que regarding the .NET Foundation request, I spoke with our executive director, Martin, this morning and he said you guys were connected. Looking forward to seeing what we can do to help you here.

[hach-que]

Yup, I managed to get in touch with him yesterday, so I'll be putting
Protobuild through the submission process over the next few days.

On Fri, Dec 11, 2015, 05:49 Beth Massi notifications@github.com wrote:

@hach-que https://github.com/hach-que regarding the .NET Foundation
request, I spoke with our executive director, Martin, this morning and he
said you guys were connected. Looking forward to seeing what we can do to
help you here.

—
Reply to this email directly or view it on GitHub
#160 (comment).

[richlander]

I finally got to looking more deeply at this PR.

There are a few aspects to this:

• Should there be a topic on cross-platform development?
• How should the topic be structured / what should it tell readers?
• Should the topic include 3rd party libraries?

I like the general idea of a cross-plat topic. Lots of library folks will want to target .NET Core and Xamarin, for example. It's good to show how .NET Core can fit into that. I believe that @cartermp has some detailed docs that explain that, which are a good candidate to link to.

The topic shouldn't describe .NET Core as one of the options. It should pivot on .NET Core, assuming that's the focal point, since these are the .NET Core docs.

The topic should describe more of the scenario. "Cross-platform" on its own is vague. I'd like to see some examples of common cross-platform targets. There is also a mixing of concerns, currently. Shared projects is a pure VS/msbuild feature. PCL is a broader feature and is meaningful at runtime. .NET Core is a platform will support for a certain set of platforms. Protobuild is a set of tools for helping you target multiple platforms within an IDE. As listed, these things all seem as peers to one another when they are not.

Adding 3rd party libraries to the .NET Core docs is OK in general, but there are a few concerns. The library has to be meaningful to .NET Core developers/users. We need to avoid situations where there are multiple solutions and choosing one to "king make". If there are multiple solutions, I'd rather describe the general concept that the solutions implement and then link out to them so that they can make their separate pitches. It also means that it needs to be OK for us to remove a reference to a 3rd party library at a later date if concerns arise.

I'd like to see the topic restructured along the lines I said. Instead of making the section "protobuild", I'd like to see it be the category that protobuild implements, start with an explanation of that category and then describe that protobuild is a solution for it.

Thoughts?

[cartermp]

I think @richlander has a good idea here.

@hach-que, is this something you're still interested in writing? It would change your current work significantly and likely be a larger writeup.

[hach-que]

That sounds like a good idea, but I'm not sure when I'll get a chance to do
it (a few other things are taking priority at the moment).

On Tue, Dec 15, 2015, 09:12 Phillip Carter notifications@github.com wrote:

I think @richlander https://github.com/richlander has a good idea here.

@hach-que https://github.com/hach-que, is this something you're still
interested in writing? It would change your current work significantly and
likely be a larger writeup.

—
Reply to this email directly or view it on GitHub
#160 (comment).

[richlander]

K. Someone should take this on or we should close the PR for now (can always be re-opened). We cannot merge the PR in its current state for the reasons given.

I'll lose the PR if I don't hear anything this week.