Documentation

[blt950]

Let's document the CC Setup & API properly, with expected returns and payloads? The readme becomes a bit too long and clunky for this purpose.

Could be done on a Github page or Wiki perhaps.

[blt950]

Alternatives:

• Github Wiki
• SSG (Hugo, MKDocs, Docusaurus, Antora etc.)
• VATSCA Wiki

[blt950]

@thor Do you want to take lead on this? If yes, feel free to self-assign this task to you. First step is perhaps to lay out pros/cons over the different SSG's?

[thor]

To move this forward, I suggest that the most critical aspect of the documentation site is its content and our ability to move it wherever necessary. We should strive to solve the user goals so our structure will be the core product regardless of how we create it.

That said, there are roughly two approaches: fully-fledged content static site generators or documentation-centric static site generators. The first has a lot of bells and whistles, whereas the second allows us to get started with less hassle.

I'll drop some names here with some examples before mentioning what I think we should start with (here aided by ChatGPT):

• So simple it's super-flexible (and examples are generally full websites)

  • Eleventy
  • Astro

• Content-focused

  • Hugo (Grafana, Netlify, Cloudflare)
  • Zola (Zola, couldn't find any bigger examples)
  • Jekyll (Jekyll itself)

• Documentation oriented

  • VuePress
  • Docusaurus (React, Material-UI, Docusaurus)
  • MkDocs (Material for MkDocs, FastAPI, Pydantic)
  • Sphinx (Jupyter Notebook)

For our goals, I'm leaning towards MkDocs or Docusaurus. The extensibility of Docusaurus is tempting, but I think it's a larger honey trap than immediately necessary for our purposes. Plus, with MkDocs, some plugins allow us to converge to multi-repo content and integrate API documentation if we want to do that.

I'll let that be enough food for thought for now. Let me know if you have any questions or objections to moving toward MkDocs, @blt950. Alternatively, it's possible to try both. Either way, the biggest job is to try to write some short and relevant documentation.

[blt950]

I read a bit up manually and asked GPT as well of the differences.

Feature	Docosaurus	MkDocs
Base Technology	React	Python
Customization	Extensive with React components	Limited; more straightforward
Markdown Support	Yes	Yes
Versioning Support	Built-in document versioning	No built-in versioning; requires plugins
Internationalization	Built-in support for i18n	Possible but requires additional configuration
Community & Ecosystem	Vibrant with many themes and plugins	Active but less extensive than Docosaurus
Complexity	Higher, suited for larger/more complex projects	Lower, ideal for simpler projects
Learning Curve	Requires React knowledge for deep customization	Easier to use, especially for Python users
Site Performance	Heavier build due to React	Generally faster and more lightweight
Ideal Use Case	Large-scale, complex docs with advanced features	Smaller, simpler documentation projects

If those are correct; I put my coin on MkDocs with Material as it's the most simple, lightweight for our very simplistic use as well. We don't really need bells and whistles for a few pages of CC documentation 😄 I at least agree that content-focused is out of the question for this kind of use.

If one of those are able to be build with Github Pages that's also a plus, so we don't need to host it completely out of the repo.