Migration of Documentation to a Dedicated Repository

[MarianRaphael]

Description

The migration of our current documentation from the central FlowFuse repository to a new, dedicated documentation repository. This will enable us to host our documentation as a standalone website, similar to our approach with Dashboard 2. The new repository will not only support Markdown but also provide enhanced capabilities for visual modifications and rich formatting to improve the usability and accessibility of our documentation.

Which customers would this be available to

Everyone - CE/Starter/Team/Enterprise

Tasks

Beta Give feedback

No tasks being tracked yet.

[joepavitt]

Just to summarise the problem here:

Working on documentation improvements is a painful developer/author experience as there is a dependency on the /website repository in order to render the docs in their "live" state. So, anyone wanting to contribute docs changes need to pull both /flowfuse and /website, have the website running in order to check how they render, etc, which is by no means "light" in it's operation and performance.

Additionally, any file changes made then take about 5-15 seconds each time for the website to refresh and reflect those changes, sometimes requiring a restart all together in the case we're adding images, etc.

Another problem is that website deployments are required for docs changes to go live, meaning that the website isn't necessarily a true reflection of the latest version of our documentation.

Proposal:
I think there is significant merit in us moving to a Vitepress docs site, as we do in Dashboard 2.0. It's all still markdown driven, so most of the content can just be transferred without change. We could then deploy to the website, via netlify, rather than as part of the website repository. This lkeaves us with two options:

1. Move the docs to a vitepress project, and into it's own standalone repo.
2. Move the docs to a vitepress project, within the core repo

Merits in making it a standalone repo:

• Much lighter-weight documentation repo makes it easier to pull, make changes and deploy
• Adding images/videos into the documentation also bloats the core /flowfuse repository, which is used by a lot of people, and feels dirty.

Merits in keeping it in core repo:

• All in one place, potentially easier to maintain

[ZJvandeWeg]

@joepavitt please move it under src/docs on the website and iterate. The docs aren't well maintained by engineering right now, having another repo isn't going to improve this.

[joepavitt]

My concern here is that we are bloating an already incredibly bloated and slow repository by doing so. Website is painful enough to work with, that would make it even worse.

My other proposal as above is keep the docs in core, but switch it to a vitepress site, so we at least have a standalone way of running docs in a lightweight isolation for faster iteration. This then raises problem of top-level navigation being inconsistent as per Dashboard docs, but the general quality would improve

[ZJvandeWeg]

Moving to vitepress doesn't magically make all those slowness issues disappear. Likely just as bad, with less features, less SEO optimisation, and just wasted cycles. If there's an issue to pinpoint to solve, let's solve that issue, but we're not going to adopt Vitepress just because it might be better

[joepavitt]

It's faster, we see that with Dashboard, instant and auto reloads when developing locally, builds far faster too?

less SEO optimisation

@Hasmin-AC suggested that actually, having https://docs.flowfuse.com would be better for SEO

[ZJvandeWeg]

@Hasmin-AC @joepavitt They'e not better: https://www.semrush.com/blog/subdomain-vs-subdirectory/

So we end up with yet another toolchain, spend engineering cycles for little user benefit, and more chaos. Again, if we're actually fixing something, let's focus on the core issue instead of adopting technology for the sake of adopting the new cool JS thing.

[joepavitt]

Just another couple of thoughts:

• We have to include maintenence label on any docs PRs in order to reflect them on the website, easily missed (e.g. Update Instance States documentation #3745 was merged, and still not live after 2 days), and means docs changes aren't updated "live"
• Having the docs live in the website repository means that issues will then often have 2 x PRs (once for website docs, and one for code) which is separation of reliability, and not a useful move.