I started experimenting with Xamarin Workbooks as a new(better) way to create my API documentation. Workbooks are an interactive combination of executable code snippets and markdown documentation.
Xamarin Workbooks is a cross platform tool both available for Windows and Mac. Download information is available here: https://developer.xamarin.com/guides/cross-platform/workbooks/install/
After installation, it is time to create your first workbook:
- Open Xamarin Workbooks. The new C# workbook window is shown. You can choose between a Console iOS, Android or WPF app(at the moment of writing).
- Xamarin Workbooks uses the concept of agents. Agents are responsible to inject and execute your code in a specific application type. This means there is a seperate agent for WPF, iOS, Android,…
- Let’s start simple and choose Console.
- You are welcomed by a blank workbook.
- In the workbook you can add two types of cells, either an executable C# cell or a documentation cell. Click on the + or “ button to add a new cell.
- In a C# cell you can enter your C# code. The workbook will provide code completion, syntax coloring, inline live-diagnostics, and multi-line statement support to optimize the editing experience.
- To execute the code you can hit <enter>, click on the play button or press <control>+<return>.
- In a Documentation cell you can enter any documentation including images. Formatting is done using the MarkDown format
Some annoyances I have at the moment:
- I noticed that the editing experience isn’t bug free yet. I got some strange behavior.
- I couldn’t find a way to include my own assemblies or use my own NuGet server.
- Compilation is (too) slow.
- No undo functionality(yet).
It will be interesting to see how this application evolves…