Should Habitat documentation be hosted on any given instance of it?

[carlnewton]

No description provided.

[carlnewton]

Embracing the federated nature of the project, perhaps documentation should be hosted on every instance of habitat itself. It would certainly help with ensuring that the version of the documentation matches the version of the instance. Translations could also use the symfony translations functionality.

[Nutomic]

Hi, I just came across your project and think that it has a lot of potential! What we initially did for Lemmy's documentation was to bundle it directly in the Docker releases so it was locally hosted on every instance. Later once we created an official project website we moved the documentation there. Alternatively you might consider using my project Ibis which allows for federated, wiki-like editing, but is still early in development (just like Habitat). The main instance ibis.wiki is meant to write about topics related to open source, such as documenting your project.

By the way if you have any questions about implementing federation or organizing a project like this, feel free to message me.

[carlnewton]

Hello! Thanks for this! Very exciting to see that someone involved in fediverse development has stumbled upon this project. Do you recall what led you to the decision to host documentation centrally? An official documentation website would be nice, so that a known URL exists, but I'm just wondering if there are any downsides to hosting it on each instance that I haven't considered yet. The big one that has come to mind so far is that Habitat is a symfony application and documentation would be best written in markdown. Whether or not I could bundle a Docusaurus directory in with the application is something I haven't yet given much thought into. I suppose there's also arguments around a monorepo being problematic.

All food for thought! I'm happy to make the mistakes early on and change things later having learned from them.

I do indeed have questions outside the scope of this issue! I will certainly be getting in touch! Thanks again!

[Nutomic]

Im not sure anymore as it was a long time ago. Most likely it was to simplify the build process for Lemmy, and to avoid centralization around lemmy.ml as everyone would link there for docs.

[carlnewton]

Ah, I can see how that would encourage more traffic to a single instance than there would need to be. Perhaps a message at the top saying something like "This documentation is specific to this instance of Habitat. For the most up-to-date Habitat documentation, visit habitat.example.com"

I've dropped a message to your Lemmy account btw. Hopefully we can get in touch, I imagine you've come across some infrastructure, contributing and hosting issues that I could learn from, as I want it to be as easy as possible to install Habitat and I don't think I'm quite there yet, and I'd appreciate being able to pick your brains!