Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So far we've used code-csharp-interactive to insert runnable C# code. Is csharp-interactive one more way?

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:
Expand Down
3 changes: 3 additions & 0 deletions styleguide/template.md
Original file line number Diff line number Diff line change
Expand Up @@ -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|
Expand All @@ -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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this paragraph be at the section above and mention code-csharp-interactive?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it fits better here, after the table with all the language tags.


The following are examples of code blocks using the language IDs for C# (\`\`\`csharp), Python (\`\`\`python), and PowerShell (\`\`\`powershell).

##### C♯
Expand Down