Dotnet-api-docs: The example seems to contain comments meant for internal (Microsoft) use

[Shah-Nisarg]

In the code example given on the page, there are several comments that say <-- Keep this information secure! -->:

//  <-- Keep this information secure! -->
    Console.WriteLine("CurrentDirectory: {0}", Environment.CurrentDirectory);

//  <-- Keep this information secure! -->
    Console.WriteLine("MachineName: {0}", Environment.MachineName);

This is confusing. It started to make sense when I looked at the result of the code sample:

This example produces results similar to the following:
(Any result that is lengthy or reveals information that should remain
secure has been omitted and marked "!---OMITTED---!".)
…
CurrentDirectory: C:\Documents and Settings!---OMITTED---!
...
MachineName: !---OMITTED---!

So it looks like those "keep this information secure" comments are meant for the documentation author as a reminder to redact sensitive information. At the moment those comments are confusing, and it may be worth removing them or adding context for the reader.

Also, I noticed that code indentation needs to be corrected as well.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: cb3fdf17-2772-6fbc-e62f-fb92a204d317
• Version Independent ID: 1918599a-dc61-962c-6227-b51684b51649
• Content: Environment Class (System)
• Content Source: xml/System/Environment.xml
• Product: dotnet-api
• GitHub Login: @rpetrusha
• Microsoft Alias: ronpet

[mairaw]

Thanks for your feedback @Shah-Nisarg. Indeed that's confusing. I think this could be a good sample to add the interactive component to it. Thoughts @BillWagner @rpetrusha? That way we could remove the expected output and customers can just see for themselves when running the sample on the browser.

[rpetrusha]

This is confusing.

The "Keep this information secure" was intended not as an internal-only comment, but as a comment for developers using the documentation -- that you generally don't want to include potentially sensitive information, such as user names, machine names, passwords, and file paths, in output. But the issue is best handled in an alert box that notes that some information should be kept secure, and in the output (where a comment can be added to information that should be considered secure).

A problem with making the sample interactive is that almost all of the output, since it reflects the Linux conventions as well as the peculiarities of the interactive playground, becomes mysterious, since the values will all be unfamiliar or unexpected to the developer.

[BillWagner]

I agree with all @rpetrusha 's comments above.

Also, I just tried some of these APIs in try.dot.net and the sensitive information is removed from the output. Running these in the interactive REPL would be even more confusing.

[mairaw]

I like that approach @rpetrusha. Adding this to our backlog then,