Recently Microsoft open-sourced Try .NET, an interactive documentation generator for .NET Core.
Try .NET is a .NET Core Global Tool that allows the creation of interactive documentation for C#. Similarly to equivalent tools targeting different programming languages (such as Jupyter), it produces documentation that can contain both explanatory text and live, runnable code.
Maria Naggaga, senior program manager at Microsoft, explained the motivation behind the development:
Across multiple languages, developer ecosystems have been providing their communities with interactive documentation where users can read the docs, run code and, edit it all in one place. [...] It was essential for us to provide interactive documentation both online and offline. For our offline experience, it was crucial for us to create an experience that plugged into our content writers’ current workflow.
All documentation is composed of markdown files containing a set of instructions and code snippets. In addition, Try .NET uses an extended markdown notation for code blocks that allows referencing a specific region within a source code file. This way, instead of writing down a code sample inside a code block, the writer can simply reference a C# region defined in another code file.
Using the extended markdown notation, a C# code block that would normally be written as:
```cs
Console.WriteLine("Hello World!");
```
Can be simply written as:
```cs --region helloworld --source-file ./Snippets/Program.cs
```
Where --region refers to the C# code #region named helloworld in the file Program.cs. More details and examples on the extended markdown notation for code blocks can be found in the tool's GitHub repository.
Another interesting feature of the tool is that it can be used in conjunction with .NET Core templates. Currently, there is only one public template available for Try .NET, created to demonstrate the markdown extension notation. However, it is possible to use the existing functionalities of .NET Core to create local custom templates for Try .NET.
Scott Hanselman, partner program manager at Microsoft, also mentioned in his personal blog that Try .NET could be used for different purposes, such as creating interactive workshops or online books:
This is not just a gentle on-ramp that teaches .NET without yet installing Visual Studio, but it also is a toolkit for you to light up your own Markdown.
The development initiative behind Try .NET started two years ago, with the release of the interactive feature on docs.microsoft.com. Interactive .NET documents also have IDE-like features such as IntelliSense (for code-completion), which provide a richer user experience. Online examples of documents generated by Try .NET can be found here and here.
