Description
@rpetrusha commented on Tue Sep 18 2018
[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 commented on Tue Sep 25 2018
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 commented on Tue Sep 25 2018
I’d start checking our top PV APIs and see the ones that make sense to apply.
@daveabrock commented on Tue Sep 25 2018
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.