Docs: [Discussion:] Determine which examples in dotnet/dotnet-api-docs should be interactive

[rpetrusha]

[Discussion:] Determine which examples in dotnet/dotnet-api-docs should be interactive

In our documentation set, interactive code examples have been used primarily for Getting Started topics for C# and .NET Core, as well as for a small number of managed APIs (such as System.DateTime, System.DateTime.Parse, and System.String.Format. Interactivity can be particularly helpful when providing documentation for APIs that developers have a difficult time understanding or that perform complex operations (such as parsing).

This is a discussion issue that aims at identifying additional examples that would benefit from interactivity. for managed reference types viewable in the API Browser and documented in the dotnet/dotnet-api-docs repo.

In some cases, interactive samples may not be practical because of (current) limitations of the repl or because of some other factors. These include:

• The REPL's local time zone is UTC. This makes it less than ideal for time zone-aware example.
• Limited use of the API.
• An API that is intuitive.

We'd welcome your thoughts about the general kinds of examples or the specific examples that would benefit from interactivity.

[ChrisMaddock]

Everything possible, would be my thoughts!

A big advantage for me would be the ability to slightly modify a sample, and then see what happens in that case. (E.g. what happens if I pass null into this method, instead of the fixed values the sample does.)

[mairaw]

I’d start checking our top PV APIs and see the ones that make sense to apply.

[daveabrock]

I would say EVERYWHERE! But to start, it would be great to have it in APIs that are straight-forward but have a lot of little trial-and-error to get right: like parsing, formatting, and regular expressions. I think it would be really valuable to try things out in that way.

[rpetrusha]

Issue moved to dotnet/dotnet-api-docs #1133 via ZenHub