diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bda1bc83faff7..15d6aca771b27 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -118,6 +118,31 @@ Your topic will also contain links to the sample. Link directly to the sample's For more information, see the [Samples Readme](https://github.com/dotnet/docs/blob/master/samples/README.md). +## The C# interactive experience # + +Short code samples in C# can use the `csharp-interactive` language tag to +specify a C# sample that runs in the browser. (Inline code samples use the +`csharp-interactive` tag, for snippets included from source, use the +`code-csharp-interactive` tag.) These code samples +display a code window and an output window in the article. The output window displays any output from +executing the interactive code once the user has run the sample. + +The C# interactive experience changes how we work with samples. Visitors can run the sample +to see the results. A number of factors help determine if the sample +or corresponding text should include information about the output. + +### When to display the expected output without running the sample + +- Articles intended for beginners should provide output so that readers can compare the output of their work with the expected answer. +- Samples where the output is integral to the topic should display that output. For example, articles on formatted text should show the text format without running the sample. +- When both the sample and the expected output is short, consider showing the output. It saves a bit of time. +- Articles explaining how current culture or invariant culture affect output should explain the expected output. The interactive REPL (Read Evaluate Print Loop) runs on a Linux-based host. The default culture, and the invariant culture produce different output on different operating systems and machines. The article should explain the output in Windows, Linux, and Mac systems. + +### When to exclude expected output from the sample + +- Articles where the sample generates a larger output should not include that in comments. It obscures the code once the sample has been run. +- Articles where the sample demonstrates a topic, but the output isn't integral to understanding it. For example, code that runs a LINQ query to explain query syntax and then display every item in the output collection. + ## DOs and DON'Ts The following list shows some guiding rules that you should keep in mind when you're contributing to the .NET documentation: diff --git a/styleguide/template.md b/styleguide/template.md index c41855a240cfa..6944327cc4e05 100644 --- a/styleguide/template.md +++ b/styleguide/template.md @@ -269,6 +269,7 @@ Use three backticks (\`\`\`) + a language ID to apply language-specific color co |AzCopy|azcopy| |C++|cpp| |C#|csharp| +|C# in browser|csharp-interactive] |F#|fsharp| |Java|java| |JavaScript|javascript| @@ -285,6 +286,8 @@ Use three backticks (\`\`\`) + a language ID to apply language-specific color co |XAML|xaml| |XML|xml| +The `csharp-interactive` name specifies the C# language, and the ability to run the samples from the browser. These snippets are compiled and executed in a Docker container, and the results of that program execution are displayed in the user's browser window. + The following are examples of code blocks using the language IDs for C# (\`\`\`csharp), Python (\`\`\`python), and PowerShell (\`\`\`powershell). ##### C♯