Reorganize the documentation

[mristin]

The current documentation is a bit confusing and missing the red thread. For example, there are missing code examples, usage examples in the console without corresponding code snippets, the structure of the arguments is not explained in the logical order (e.g., the default values are not clearly explained), the documentation is scattered between the wiki and docs/ folder etc.

I would suggest to put it all in one place and differentiate between different sections:

• API documentation,
• Getting started,
• Recipes (Tutorials?) and
• Contributing guidelines.

I personally think that just using markdown in doc/ folder doesn't actually cut it for a library with such a wide scope. The files need to be referenced manually, the missing links are hard to detect etc. The wiki is also not really appropriate, since it is not versioned together with the code (e.g., changes in API should go along with changes in the documentation).

IMHO, it would be better to set up docfx and start properly structuring the documents in different sections. Even if we start with very few articles per section in the beginning, having a predefined structure would greatly facilitate adding new nuggets of information (e.g., adding further recipes with code examples).

Furthermore, docfx would automatically generate API documentation from the code upon each change to the master branch. I would also suggest to use doctests as much as possible for methods where it makes sense. (I implemented a doctest tool for C#, but maybe you know a better one).

@jonsequitur and others: what do you think? I would be glad to make the effort and set up docfx. I am not familiar with Azure Pipelines that you use -- so somebody else would need to automate document generation.

A subset of related issues: #984, #987, #940

[jonsequitur]

The /docs folder is a copy of the wiki, with some additional changes. The wiki should be removed at this point. And in fact our goal is to create docs using docfx and transition the documentation to docs.microsoft.com.

A secondary goal of moving the docs into the repo is to take advantage of dotnet-try to compile-check the code samples during CI and allow people to run them interactively if they clone the repo. It looks like this overlaps somewhat with your doctest tool and I'd be interested to do a comparison of scenarios between the two.

See also: Area-Documentation

[mristin]

@jonsequitur thanks for the clarification!

The /docs folder is a copy of the wiki, with some additional changes. The wiki should be removed at this point. And in fact our goal is to create docs using docfx and transition the documentation to docs.microsoft.com.

Would you like me to set up the docfx (docfx/ folder)? We can start slow and publish the docfx-generated documentation to Github pages for the moment as long as you don't set up the pipeline for docs.microsoft.com. Or you would prefer not to at the moment and postpone docfx to a much later time point?

A secondary goal of moving the docs into the repo is to take advantage of dotnet-try to compile-check the code samples during CI and allow people to run them interactively if they clone the repo. It looks like this overlaps somewhat with your doctest tool and I'd be interested to do a comparison of scenarios between the two.

Both tools aim at very similar goals. Dotnet-try feels at the first glance way "heavier" than doctest-csharp. Doctest-csharp extracts the examples from the structured code comments and converts them to unit tests. Hence the snippets remain static, but if integrated properly in CI, the bugs would show up when the documented examples fail the tests I haven't included support for markdown files in doctest-csharp as I didn't originally need it (only structured comments are currently supported).

Dotnet-try provides interactive REPL and allows the reader to play with the code. This is much more involving (hence heavy), but also more useful for quick testing. If I read correctly, only markdown files are supported.

I suppose both tools can be easily extended to handle both structured comments and markdown files. The reader of doctest snippets needs no dependency (and can read the documentation off-line as PDF), while dotnet-try requires Visual Studio at the moment (if I read its readme correctly).

[chhh]

my 2c - dotnet-try didn't work for me, started throwing cryptic errors.

[jonsequitur]

Setting up DocFx would be great.

dotnet-try's extended Markdown provides the context in which code samples can be compiled and executed by referencing a sample .NET project. It works for both C# and F# and provides a couple of gestures for maintaining non-interactive docs:

• dotnet try verify ensures that the Markdown docs reference valid code samples in the backing project, and
• dotnet try publish inlines code samples and their output into the Markdown (or HTML) for static viewing, e.g. on GitHub), to make sure the docs are up to date.

Some code samples under /docs were created this way, like this one: https://github.com/dotnet/command-line-api/blob/master/docs/model-binding.md. It has no dependency on Visual Studio.

[jonsequitur]

my 2c - dotnet-try didn't work for me, started throwing cryptic errors.

@chhh What error did you see and what version of dotnet-try are you using?

[mristin]

@jonsequitur do I understand that right: the workflow for docs with code samples is: write a .cs file, reference it in the markdown file, dotnet try verify checks that the file references are correct, dotnet try publish would inline the code and finally docfx generates the html?

That also explains why all the snippets in the docs were empty -- I didn't understand that part :).

Doctest-csharp is then indeed orthogonal. It extracts the snippets from the comments in code to create unit tests, so exactly the reverse. I personally find that direction more logical (coming for Python), but that's subjective.

Is there a way to use dotnet try verify to check both the references and content so that the content is not invisible for the developer at the presentation site? That is, check that the content of the file would coincide with dotnet publish?

Would that approach be also possible with <code>...</code> in the code base? That was meant to be the actual use case for doctest-csharp.

Regarding Visual Studio: I was confused by the readme: https://github.com/dotnet/try#interactive-net-core-documentation-with-the-dotnet-try-global-tool

[jonsequitur]

Is there a way to use dotnet try verify to check both the references and content so that the content is not invisible for the developer at the presentation site?

During authoring, I find the best approach is to run dotnet try /path/to/root/of/docs and when you make some changes to either the Markdown or backing code, just refresh the dotnet try page. You'll see the latest code there and you can run it.

When you're ready to publish, run dotnet try publish and if fills in the code samples in the Markdown. (It also does a build verification before inlining the code.)

dotnet try also supports using the Markdown file as the source of truth but using the backing project as the source of truth fits more smoothly with the complex tooling of package updates, refactoring, etc.

[chhh]

@jonsequitur It was a while ago, don't remember exactly, it was some uninformative message in the browser like Server error occurred without any further details.
What I was trying to say was that by adding extra layers of unnecessary complication you're only creating extra maintenance problems. How likely do you think is it that a person searching for cmd-line parsing lib doesn't have any tooling already installed on their machine and ready to copy/paste an example?

[mristin]

@jonsequitur thanks for the information, I'll give it a try.

Should I still set up doctest-csharp to be used for testing examples in the structured comments or you prefer to leave the snippets unchecked?

[jonsequitur]

What I was trying to say was that by adding extra layers of unnecessary complication you're only creating extra maintenance problems.

dotnet try reduces maintenance issues by automating the verification of sample code during authoring and CI. The output is a normal Markdown file including code samples, like this: https://github.com/dotnet/try#interactive-net-core-documentation-with-the-dotnet-try-global-tool. End users don't need to install anything.

[mristin]

Hi @jonsequitur ,
Sorry for the silence on my side. It's a busy summer and the heat does not help. I'll try to start with the docs later this week.

[jonsequitur]

Not to worry. Thanks for your help!

[mristin]

Hi @jonsequitur ,
I spent about an hour today looking into the build process and where the documentation building would fit in. Unfortunately, it was overwhelming -- I don't feel confident enough to really touch it, add the extra dependencies etc..

Could somebody else initiate the "plumbing", while I'd fill in the content? If not, could we schedule a call so that you (or somebody else) give me the big picture of the build process?