Plan for documentation

We need to start having some documentation so need to decide how this will look. Some of the decisions needing to be made are:

• Where will the raw docs live
• What tooling to use
• Where will the published docs live

Some of these decisions are inter-related, for example having the documentation on readthedocs.io would be easiest using Sphinx or MkDocs for documentation generation (although it does support creating your own custom docs build system, I really don’t want to maintain something too custom like that).

Raw documentation location I see 3 potential options:

1. In a docs folder at the root of the master branch of the CoreWCF/CoreWCF repo
2. In a special docs branch in the CoreWCF/CoreWCF repo, similar to how github pages publish from a gh-pages branch
3. In a separate repo in the CoreWCF org. E.g. CoreWCF/Docs

One thing to consider is that the documentation will eventually be quite substantial in size. It’s because of this that I didn’t list the option of inline documentation in the code. I believe CoreWCF documentation would be too large to place inline.

Tooling I had a quick look around and these are the options I’ve come across. Feel free to add any more I may have missed.

1. Sphinx (link)
2. MkDocs (link)
3. DocFX (https://dotnet.github.io/docfx/)

For completion, I’ll mention there are in-line code comment based documentation tools such as doxygen. As I already mentioned, because the WCF documentation tends to be very large, I don’t think it’s appropriate to place this inline with the code.

Published documentation location I see there being a few options.

1. https://corewcf.readthedocs.io/ as is currently listed in the contributing guide.
2. Github pages
3. A potential future site hosted by dotnetfoundation as suggested in dotnet-foundation/projects#21

[clairernovotny]

I will note that the .NET Foundation is putting together a docs site, docs.dotnetfoubdation.org. Our goal is to use the same platform as MS docs and would be using DocFX.

We’d be happy to work with you to get this done.

[dotMorten]

I’d be happy to provide some pointers on integrating with DocFX and GitHub actions. As a reference, you can use one of my repos as reference Published Github Pages: https://dotmorten.github.io/NmeaParser/ DocFx configuration: https://github.com/dotMorten/NmeaParser/blob/main/docs/docfx.json GitHub action for auto-updating github pages: https://github.com/dotMorten/NmeaParser/blob/main/.github/workflows/ghpages.yml

This probably does way more than you need because of the need to deal with multi-targeted APIs that actually differ per target.

Probably my favorite feature of docfx is it’s integration with GitHub where each page has an “improve this doc” section that takes you straight to making a PR that improves the doc, and the API reference has links straight to the source code of each member.

The biggest problem I see right now though is the lack of xml doc in the source code.