Documentation Hosting

[johnbwoodruff]

This issue is probably more of a discussion for collaborators but of course anyone is welcome to chime in with opinions. Once Cord (the company) shuts off their infrastructure then obviously the documentation site will be offline. If people need documentation they can, of course, pull down this repo, get it set up, and serve the documentation themselves. However, I believe it would be beneficial at some point to host the documentation and link to it from this repo. That decreases the effort to get started using Cord. The way I see it, there are a few options.

1. Host the existing docs on GitHub Pages. I'm not certain if that's possible today with no changes, as it seems there is a server component to the built docs and I have not looked fully into it yet.
2. Host the existing docs on some other infra. This obviously will likely have cost associated with it, so unless there is someone or some company willing to eat that cost I don't think this is a viable option.
3. Use something like Read the Docs as they have a free open source plan, but that would obviously require re-documenting everything there. Not ideal unless someone really loves writing documentation or is willing to put in that time. That said, it may be a good longer term option which would then let us remove all the docs code in the repo, simplifying things.
4. Re-write the docs using some other tool to generate a purely static site with no server component at all, which would allow us to easily host this from this repo using GitHub Pages. This is another longer-term option given the time investment that would be needed to re-write the docs using another tool.

I'm hoping there are other much better options I'm just not aware of, which is a big reason for having a public discussion on this subject. The important thing to keep in mind is Cord is shut(ting) down so any effort from here on out is entirely voluntary and community driven. That said, I'm looking forward to the discussion.

[rusackas]

Most open source foundations provide some sort of free infra services for project websites. Probably TMI, but for Superset, we use Docusaurus, and have an npm script that renders out the static HTML site. We then use a GitHub action that runs to execute that script and copy the resulting static site files over to another ASF repo. That repo has branches set up that are hosted (for free) by ASF infra.

If you happen to have the bandwidth to convert to a static site generator (gatsby, jekyll, etc... there are probably lots of them now), they could likely deploy to GitHub pages for free in a similar fashion. That's a project though, so non-trivial

Alternatively, being open source, you could probably just run the whole thing as-is, using Netlify. They have free open source plans, and could likely host the server app as-is. The same may be true for other services (Vercel, etc.)

[jwatzman]

A few random thoughts from an ex-Cord person. Hopefully this is useful, and hopefully it is correct through already-hazy memory; obviously ignore me if not, and apologies if this is covering ground you already had figured out yourselves!

The way the docs are structured now aren't super amenable to converting to a static-site generator. The docs are currently a React app, and we took advantage of that in a number of places. The simplest is just that we define consts for page names and URLs etc and cross-include in a few places, notably for the navigation, one example here. We then do fancier things like dynamically showing the React SDK 1.0 components and 2.0 components (unreleased/unfinished when Cord shut down) depending on some factors I forget (this is the version field in navigation.tsx). Up to the fanciest, which is a script which processes the React/types SDK docblocks and generates TS files that the docs use (e.g., see all uses of this import) -- notably we don't use this in a consistent way, or even consistently at all, often extracting the specific bits we need and adding more detail around the raw docblocks in a very context-sensitive way.

We also take advantage of this for the live demo components, by just throwing the relevant component onto the page. This relies on a special Cord token being in a Cord provider set up higher in the page, but since it's just a React app you can just do that.

All of this can be expressed in a static site generator, but it gets messy quickly IMO. These sorts of generators require you to define a structure that everything has to fit into, and then define the content -- you can't "just do shit", and we "just do shit" everywhere, prioritising docs that are complete and are at least locally sensible over something that has clean semantic consistency everywhere.

In fact, I know this can all be expressed in a static site generator because the previous version of the docs was in fact built with one -- Jekyll IIRC? It was too hard to work with -- we weren't properly documenting things because they didn't fit into the rigid structure and it was such a pain to change the structure when you just wanted to put a warning box over there or something -- and so the entire thing was rewritten as a React app. It was so much nicer to be able to just do whatever. And we do have a bunch of common components providing a good deal of consistency and structure, but you can easily go around them when you need something else.

You can disagree with the philosophy (though I strongly feel it was right!) but as a matter of what exists right now, the docs site is that way, and so conversion to a static site generator isn't easy.

You might have more luck exporting everything to HTML and just serving that -- it's designed to be server-side rendered anyway, though uses completely custom SSR hydration etc, not sure how much more complicated that makes doing that. You'd lose the live demos though by doing this, I think, without some care.

So I'd recommend just running the site as-is, pointed at someone's hosted Cord installation for the live demos, if you want to keep those.

[johnbwoodruff]

@jwatzman Thanks a bunch for the awesome context! Don't worry nobody here is going to argue how anything was done previously, those decisions all totally make sense to me. I mostly want to figure out something for the future of the open source project that is feasible. I think the best solution would definitely be to run the docs as they are today, but like you said that would require being pointed to someone's hosted instance, and I think that's the biggest obstacle to overcome since that has associated cost and other implications.

The good news is anyone who needs the docs can pull the repo and run the stack locally, which includes the docs, so nobody is prevented from accessing the documentation, which is the most important thing.