From 0e6c72fa7782f79d04fec3c5e013790db224fac0 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Wed, 28 Mar 2018 13:44:46 -0400 Subject: [PATCH 1/2] include interactive guidance Fixes #4571 We asked users how they want to work with interactive samples. Whether they want comments, or output included --- CONTRIBUTING.md | 23 +++++++++++++++++++++++ styleguide/template.md | 3 +++ 2 files changed, 26 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bda1bc83faff7..a00cc55c87b97 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -118,6 +118,29 @@ 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 run in the browswer. When these sample are built, the code sample +displays as a code window and an output window. 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 by running the sample. 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 text formatting 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 runs on a Linux based host. Culture-specific output is different for different OSes 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. 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..1efb9392c91e0 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♯ From e1a1225fa6393aa8582554c93b65ca7fa62f5def Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Wed, 28 Mar 2018 22:22:45 -0400 Subject: [PATCH 2/2] respond to feedback. --- CONTRIBUTING.md | 14 ++++++++------ styleguide/template.md | 2 +- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a00cc55c87b97..15d6aca771b27 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -121,25 +121,27 @@ For more information, see the [Samples Readme](https://github.com/dotnet/docs/bl ## The C# interactive experience # Short code samples in C# can use the `csharp-interactive` language tag to -specify a C# sample that run in the browswer. When these sample are built, the code sample -displays as a code window and an output window. The output window displays any output from +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 by running the sample. A number of factors help determine if 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 text formatting should show the text format without running the sample. +- 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 runs on a Linux based host. Culture-specific output is different for different OSes and machines. The article should explain the output in Windows, Linux, and Mac systems. +- 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. For example, code that runs a LINQ query to explain query syntax and then display every item in the output collection. +- 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 diff --git a/styleguide/template.md b/styleguide/template.md index 1efb9392c91e0..6944327cc4e05 100644 --- a/styleguide/template.md +++ b/styleguide/template.md @@ -269,7 +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} +|C# in browser|csharp-interactive] |F#|fsharp| |Java|java| |JavaScript|javascript|