Should we move to Wyam?

[jzabroski]

• DocFX is currently only supported on .NET Framework
  • This means you can only build the documentation on Linux using Mono instead of .NET Core
• Wyam seems to be moving faster than DocFX
  • DocFX is idiosyncratic and tightly coupled to Markdown syntax
  • DocFX initially grew to popularity because it was easy to get up-and-running with its built-in template system and decent sample templates, but once you start using a template system, you're not easily able to extend it.
  • Wyam is effectively like using Razor Pages to extend Markdown. Examples are Wyam Modules which let you transform one mime-type into inline static HTML content
• The wyam.io website is beautiful, much more so than https://docs.microsoft.com , which may suggest it is strictly better
• Rapid prototyping features
  • .\Wyam.exe preview is a nice REPL for previewing changes as you make them.
  • Wyam.Core nuget package lets you embed it directly into projects, so for customers who have customized their own in-process migration runner, they can even easily offer a static documentation site on their own intranet.

[fubar-coder]

One very nice feature of DocFX is the inclusion of the BCL API, which allows one to go from your own documentation to the documentation of - for example - the System.String class for string parameters. But this feature has some weird bugs...

Wyam looks nice and - more importantly - works with disabled JS. How is the support for multiple API versions? This would be a real killer feature.