Please improve DocFX documentation

[nathan-alden-sr]

It seems strange that a project whose purpose is to build documentation itself has such poor documentation. The DocFX tool and concept seem very cool and flexible; however, there is apparently no official documentation describing the architecture of DocFX--what each concept means, how they relate, etc. (documentation about the domain model of the tool)--nor is there detailed documentation about the docfx.json configuration file (yes, there is a JSON schema but that is too fine-grained to be of much use).

I was told there is a v3 of DocFX underway. Please consider greatly enhancing DocFX documentation to better introduce new folks to the tool and its model. Adoption will likely increase greatly if you do this.

[grokys]

PLEASE! I've just come to docfx again after several years and disappointed to find the documentation as obtuse as ever. @nathan-alden-sr correctly points to the docfx.json documentation being bad, but the documentation for theming is even worse.

[mdschweda]

Agreed. The state of the documentation is quite ironic for a documentation tool.

[AZ-X]

Quite agreed. I just narrow down to a sub project called ‘MarkdownLite’. The codes inside this project are strange to me, while pattern’s names are superficial in everywhere.

[yufeih]

Thank you Nathan, these are all great feedbacks and I share the same feeling. There are so many areas to improve for a project whose whole purpose is to create documentation. I took some time to rework some of the docs to be more customer facing and hopefully it'll make it easier for people to understand and follow along.

There are much more improvements needed and we need the community's help to make the documentation better, so I'm converting this issue into a discussion for the community to collaboratively discuss and improve the product docs.

[KalleOlaviNiemitalo]

The documentation of the docfx.json configuration file in https://github.com/dotnet/docfx/blob/v2.60.0/docs/docs/config.md omits at least the xrefService, dest, and template properties of build. https://github.com/SchemaStore/schemastore/blob/8778c9f9ebeb448d0336209f9092fdc9ed6d97f2/src/schemas/json/docfx.json does not describe all of those, either.

[Stoffelche]

At least one can use google cache to find part of the old documentation

[paulushub]

At least one can use google cache to find part of the old documentation

Or simply generate it yourself.

[Stoffelche]

All the links found anywhere are broken with the old documentation is gone, like for example on this page:
https://microsoft.github.io/code-with-engineering-playbook/documentation/recipes/using-docfx-and-tools/

[killeriukas]

There was more documentation under Specifications tab as well. It was very helpful learning the nitty gritty stuff. Would be lovely if all of it was returned under the Obsolete tag as well. Thanks.

[tibitoth]

I'm really considering to move away from docfx to MKDocs Material. Maybe try to integrate docs generation from assembly into MKDocs but handwritten docs we will use MKDocs only.

[Stoffelche]

Are you generating the api documentation for c# projects with MKDocs as well? If so, how?

[tibitoth]

I've just done some investigation on this topic and sadly there is no easy way to achieve this because of this issue #684 It seems like docfx do not create inmediate MD files and the process looks like this: .dll => .xml => .yml? => .html