What's the documentation surface for MTConnect.NET — keep docs/*.md, build a static site, or other?

[ottobolyos]

Draft GitHub discussion — documentation site / docs/index.html strategy

Repository: TrakHound/MTConnect.NET
Type: discussion (Q&A)
Audience: @PatrickRitchie
Author: Otto Bolyós (@ottobolyos)
Status: draft — review before filing

---

Title

What's the documentation surface for MTConnect.NET — keep docs/*.md, build a static site, or other?

Body

docs/index.html is currently 12 bytes (HELLO WORLD), single commit cb48e674 Create index.html, no references anywhere in the repo (grep is empty), no .github/workflows/pages.yml / Jekyll config / VitePress config / DocFX config. Looks like a placeholder for a docs-site setup that didn't materialise.

The existing docs/*.md topic files (Json.md, MQTT-Protocol.md, MQTT-Topics.md, InfluxDB.md, OpenSSL.md) are already discoverable on GitHub's source view + the per-version compliance docs from PR #139 add docs/testing/v2-6.md + docs/testing/v2-7.md.

A few questions to sort the documentation strategy:

1. What audience is the documentation aimed at? End users consuming the NuGet packages? Maintainers / contributors? Both?
2. Is a hosted docs site at https://trakhound.github.io/MTConnect.NET/ (or similar) in the roadmap? The existing docs/index.html placeholder + the empty Pages config slot suggest it was at one point.
3. What documentation tooling do you prefer if a site lands? Three common options:
   • VitePress — Markdown-driven, fast, modern. Builds at apps/docs/ with a GitHub Actions deploy job.
   • Docusaurus — Markdown + React components, larger surface but more flexible.
   • DocFX — .NET-native, can ingest XML doc-comments from the source for API reference.
4. If a site doesn't land, should docs/index.html be deleted or replaced with a docs/index.md hub page that links to the existing topic docs + the per-version compliance pages?

Happy to do whichever you prefer — say the word and I'll pick it up after PR #139's batch lands. If it's a "not yet a priority" answer, that's fine too — I'll just delete the empty index.html placeholder so it stops looking like a half-done setup.

[PatrickRitchie]

1. Yes the idea was to host a documentation site. I did a couple prototypes but never published anything.
2. The existing index.html page was mainly just to test how GitHub pages work
3. Yes using an existing framework would be preferred. VitePress looks promising.

Documentation is a priority, I just haven't had a chance and was hoping I could use some AI tools to generate most of it.

[ottobolyos]

Okay, then VitePress it is (I use it all the time) with the Mermaid plugin (for diagrams and flowcharts—IMHO they look better than ASCII ones), however, i'd defer it after you review and merge the existing PRs.