Skip to content

include interactive guidance in our contributing guide. - #4805

Merged
mairaw merged 2 commits into
dotnet:masterfrom
BillWagner:update-contributor-guide-for-REPL
Mar 31, 2018
Merged

mairaw merged 2 commits into
dotnet:masterfrom
BillWagner:update-contributor-guide-for-REPL

Conversation

@BillWagner

Copy link
Copy Markdown
Member

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.

Fixes #4571

We asked users how they want to work with interactive samples. Whether they want comments, or output included
@BillWagner
BillWagner requested review from mairaw and rpetrusha March 28, 2018 17:52

@ChrisMaddock ChrisMaddock left a comment

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.

Can't wait for this to become more widespread. 😄

Comment thread CONTRIBUTING.md Outdated
## 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

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.

'browswer' 😄

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.

Also, 'When these samples are built'?

Comment thread CONTRIBUTING.md Outdated
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

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.

"Visitors can run the sample to see the results by running the sample."?

Comment thread CONTRIBUTING.md Outdated
### 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.

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.

nitpick - double space!

Comment thread CONTRIBUTING.md Outdated
- 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.

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 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?

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.

(It may be that I'm wrong here, instead!)

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.

@ChrisMaddock, at some point, culture will be taken from the user's browser. But at the moment, the invariant culture is used.

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.

Ah ok. Thanks!

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.

  • 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?

Comment thread styleguide/template.md Outdated
|AzCopy|azcopy|
|C++|cpp|
|C#|csharp|
|C# in browser|csharp-interactive}

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.

Accidental curly brace, I think!

Comment thread CONTRIBUTING.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?

@rpetrusha rpetrusha left a comment

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.

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.

Comment thread CONTRIBUTING.md Outdated
## 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

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.

run --> runs
When these sample are built, the code sample --> When such a sample is built, it

Comment thread CONTRIBUTING.md Outdated
### 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.

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.

text format --> formatted text

Comment thread CONTRIBUTING.md Outdated
- 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.

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.

@ChrisMaddock, at some point, culture will be taken from the user's browser. But at the moment, the invariant culture is used.

Comment thread CONTRIBUTING.md Outdated
### 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.

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.

understanding --> understanding it

Comment thread styleguide/template.md
|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.

Comment thread CONTRIBUTING.md Outdated
- 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.

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.

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 mairaw left a comment

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.

Folks already got most of the comments I'd make covered. Added just one more.

Comment thread CONTRIBUTING.md Outdated
- 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.

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.

  • 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?

@mairaw
mairaw merged commit 202c7d2 into dotnet:master Mar 31, 2018
@BillWagner
BillWagner deleted the update-contributor-guide-for-REPL branch March 31, 2018 21:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants