Repository navigation
include interactive guidance in our contributing guide. - #4805
Conversation
Fixes #4571 We asked users how they want to work with interactive samples. Whether they want comments, or output included
ChrisMaddock
left a comment
There was a problem hiding this comment.
Can't wait for this to become more widespread. 😄
| ## 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 |
There was a problem hiding this comment.
Also, 'When these samples are built'?
| 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 |
There was a problem hiding this comment.
"Visitors can run the sample to see the results by running the sample."?
| ### 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. |
There was a problem hiding this comment.
nitpick - double space!
| - 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. |
There was a problem hiding this comment.
Should this point mention that the culture is taken from the users browser? That's what I understood from your previous post on the issue, but I'm not sure it's so clear here?
There was a problem hiding this comment.
(It may be that I'm wrong here, instead!)
There was a problem hiding this comment.
@ChrisMaddock, at some point, culture will be taken from the user's browser. But at the moment, the invariant culture is used.
There was a problem hiding this comment.
- nit: Linux based -> Linux-based
- OSes is the wrong acronym. The correct one is actually OSs, which I find awful, so I always spell out operating systems. 😆 Fun read
- define the REPL acronym?
| |AzCopy|azcopy| | ||
| |C++|cpp| | ||
| |C#|csharp| | ||
| |C# in browser|csharp-interactive} |
There was a problem hiding this comment.
Accidental curly brace, I think!
|
|
||
| ## The C# interactive experience # | ||
|
|
||
| Short code samples in C# can use the `csharp-interactive` language tag to |
There was a problem hiding this comment.
So far we've used code-csharp-interactive to insert runnable C# code. Is csharp-interactive one more way?
rpetrusha
left a comment
There was a problem hiding this comment.
Generally looks good, @BillWagner. @ChrisMaddock has suggested some changes and corrections, as have I. Once you address them, you can mark this as ready to merge.
| ## 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 |
There was a problem hiding this comment.
run --> runs
When these sample are built, the code sample --> When such a sample is built, it
| ### 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. |
There was a problem hiding this comment.
text format --> formatted text
| - 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. |
There was a problem hiding this comment.
@ChrisMaddock, at some point, culture will be taken from the user's browser. But at the moment, the invariant culture is used.
| ### 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. |
There was a problem hiding this comment.
understanding --> understanding it
| |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. |
There was a problem hiding this comment.
Should this paragraph be at the section above and mention code-csharp-interactive?
There was a problem hiding this comment.
I think it fits better here, after the table with all the language tags.
| - 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. |
There was a problem hiding this comment.
I read Culture-specific output is different for different OSes and machines as formatting with the same culture (even invariant) produces different results on different OSes and machines. How much is it true? Does setting current culture to a certain value within the code snippet make output more independent from the host?
mairaw
left a comment
There was a problem hiding this comment.
Folks already got most of the comments I'd make covered. Added just one more.
| - 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. |
There was a problem hiding this comment.
- nit: Linux based -> Linux-based
- OSes is the wrong acronym. The correct one is actually OSs, which I find awful, so I always spell out operating systems. 😆 Fun read
- define the REPL acronym?
Fixes #4571
We asked users how they want to work with interactive samples. Whether they want comments, or output included. We learned a lot, and updated our guidance based on the feedback.