Explanation in "docs/GettingStarted/ReadOnlySnippets.md" raises more questions than answers.

[lord-saumagen]

Describe the bug

The whole page appears to be unrelated to the topic which should be explained in this page.

Did this error occur while using dotnet try or online?

• dotnet-try
• .NET Jupyter Notebook
• online

What kind of error was it?

• User Interface (UI): For example the output never displayed
• Service Error: For example "The service is temporarily unavailable. We are working on it"
• Other:

Since there is more than one error in this page, I'm going through the errors by number.
I'm starting with the errors in the rendered output of that page. Please take a look at the first screenshot.

1. The link doesn't work because the referenced file doesn't exist.
2. There is no explanation why there are using directives an how the directives relate to the topic.
3. There is no explanation where the "DataObject" is declared, why it is necessary or how it is used in the context of creating a read only snippet.
4. The same as 3.
5. There is no explanation where the "counter" variable is declared or how a read only variable relates to the topic of creating a read only snippet.

Since the rendered page failed to explain anything related to the topic, I took a look at the source code. Please take a look at the second screenshot.

I found the using directives at marker 2. Attached to the fencing there is the region attribute referencing a "usings" region --region usings. Since the "ReadOnlySnippets.md" file is part of the project which gets created when you run

dotnet try demo

I searched for a "usings" region in the csharp project files. But there is no "usings" region declared in any of that files. That leaves the "usings" directive declared before the Snippets.Program declaration further down in the document. But there is no description that one can use the --region attribute like some kind of include reference. Neither in the "Regions.md" file, nor in this file.

There is also a --editable false attribute attached to the fencing. I guess that is the attribute which should be discussed in the "ReadOnlySnippets.md" file in the first place. A snippet which is not editable must be read only, right? But that attribute isn't discussed in any of the markdown files.

The same is true for the --destination-file ./Snippets/Program.cs attribute attached to the fencing. There is a description for the --source-file attribute in the "QuickStart.md" file. The description for this attribute is:

Points to the file where the sample code is pulled from.

So I guess that in contrast, the --destination-file attribute points to the file where the sample code is put to. (Or in other words where the sample code will be saved.) But a test showed that this isn't true. There is already a Program.cs file in the Snippets directory of the project. But that file doesn't change when you run the dotnet try program.

So, what is the purpose of the --destination-file attribute and how does it work?

I found the DataObject class definition at marker 3, but the class as well as the included function at marker 4 are never referenced or used in the "ReadOnlySnippets.md" file.

There is another useless class definition for the HiddenObject at marker 2.1. and for the ProgramUtility at marker 2.3.

The Program class definition finally revealed the counter declaration at marker 5. But the class has also a useless region declaration #region run2 at marker 2.2. The region is never referenced. Only the region #region run1 is reference. Since the content of region run2 is the same as the content of region run1 the whole region is superfluous in the first place.

Conclusion

Obviously the content of the "ReadOnlySnippets.md" file is a copy of a file which was created to explain a totally different topic. The file raises a bunch of questions but doesn't explain how to create a read only snippet.

The file also raises the questions how many "markdown - dotnet try" attributes there exist in total and whether there is an overview of all this attributes with a meaningful explanation. That overview might already exist but I couldn't find it yet.

Please create a markdown page which explains how to create a "ReadOnlySnippet" and please add the pages which explain the attributes which aren't explained yet (like the destination-file attribute or the editable attribute) to the demo project.

I like the idea of interactive code examples in documentation files, but the documentation for this project is unfortunately a bummer. So I'm looking forward to the day where the documentation for your project becomes a shiny reference for superb documentation. (That's what the whole project is about, right?)

Kind regard, Lord Saumagen.

Screenshots

First screenshot, rendered page

Second screenshot, source code