A New Docs Platform? #665

New Issue

3wordchant · 2025-01-03T07:16:04Z

3wordchant commented

2025-01-03 07:16:04 +00:00

Needing to do $python_virtualenv_stuff to install a mkdocs plugin – and the difficulties in reorganising the menus that we discovered in #664 raised the question of whether there's a better docs platform we could use.

Let's discuss!

Needing to do `$python_virtualenv_stuff` to install a `mkdocs` plugin – and the difficulties in reorganising the menus that we discovered in #664 raised the question of whether there's a better docs platform we could use. Let's discuss!

❤️ 1

3wordchant added the

documentation

label 2025-01-03 07:16:25 +00:00

3wordchant commented

2025-01-03 07:16:51 +00:00

From The Matrix:

concrete hypothetical example renaming "operators" to "frobnicators"

hypothetically: https://docs.coopcloud.tech/operators/ is now https://docs.coopcloud.tech/frobnicators/
currently mkdocs will happily build even if internal links, and even our nav menu, point to /operators, and will just leave missing nav links and broken internal links
(it's possible if we changed how we do internal links, and if we changed how our nav menu is generated, this could be mitigated, but still not perfectly, and following problems remain)
there are two "better" case scenarios here as far I can tell
firstly, for internal links, e.g. /abra/upgrade links to /operators/handbook, our docs system could either rewrite or redirect. from what I understand Outline does this (internal links to pages are automatically rewritten) and Mediawiki also achieves this (by adding redirects from old to new page names)
secondly, for incoming links from elsewhere, if there's a blogpost out there which links to /operators/handbook, then our docs system could automatically send people to /frobnicators/handbook
I agree that we could add Traefik redirects for /operators/* -> frobnicators/*. given our current situation where we need a separate app for that, it seems even gnarlier than anything we need to do in mkdocs so far. not only is it potentially a separate repo / syntax, it requires manual mapping of what moved where
I believe Mediawiki handles this second case, again because of the automatic redirects, but Outline potentially doesn't? for comparison I think Wordpress can do this with a plugin but not by default
realising this should probably be a ticket 😳

From The Matrix: > ## concrete hypothetical example renaming "operators" to "frobnicators" > hypothetically: https://docs.coopcloud.tech/operators/ is now https://docs.coopcloud.tech/frobnicators/ > currently mkdocs will happily build even if internal links, and even our nav menu, point to /operators, and will just leave missing nav links and broken internal links > (it's possible if we changed how we do internal links, and if we changed how our nav menu is generated, this could be mitigated, but still not perfectly, and following problems remain) > there are two "better" case scenarios here as far I can tell > firstly, for internal links, e.g. /abra/upgrade links to /operators/handbook, our docs system could either rewrite or redirect. from what I understand Outline does this (internal links to pages are automatically rewritten) and Mediawiki also achieves this (by adding redirects from old to new page names) > secondly, for incoming links from elsewhere, if there's a blogpost out there which links to /operators/handbook, then our docs system could automatically send people to /frobnicators/handbook > I agree that we could add Traefik redirects for /operators/* -> frobnicators/*. given our current situation where we need a separate app for that, it seems even gnarlier than anything we need to do in mkdocs so far. not only is it potentially a separate repo / syntax, it requires manual mapping of what moved where > I believe Mediawiki handles this second case, again because of the automatic redirects, but Outline potentially doesn't? for comparison I think Wordpress can do this with a plugin but not by default > realising this should probably be a ticket 😳

kawaiipunk commented

2025-01-06 11:40:35 +00:00

My perspective:
Asking community members to use mkdocs to edit the wiki, you're already loosing 90% of possible contributors that might not yet have the skills to use it (even assuming we're not hitting technical difficulties). I do have some skills in this area and even I struggled when I hit weird dependency bugs specific to my setup which were hard for other folks to support with.

Also, it's required to use the wiki to make proposals so that affects the democratic participation of the collective.

The drawbacks of moving to a more GUI based wiki are logins! SSO, all this kind of stuff. Need to think that through. I liked the idea of using git.coopcloud.tech as an SSO provider if that is possible.

My perspective: Asking community members to use mkdocs to edit the wiki, you're already loosing 90% of possible contributors that might not yet have the skills to use it (even assuming we're not hitting technical difficulties). I do have some skills in this area and even I struggled when I hit weird dependency bugs specific to my setup which were hard for other folks to support with. Also, it's required to use the wiki to make proposals so that affects the democratic participation of the collective. The drawbacks of moving to a more GUI based wiki are logins! SSO, all this kind of stuff. Need to think that through. I liked the idea of using git.coopcloud.tech as an SSO provider if that is possible.

decentral1se commented

2025-01-06 12:07:19 +00:00

Idk if it covers all the features we need but dokuwiki has SSO support, is file based, has a decent GUI and supports markdown. it takes a few plugins but it is feature rich. it's been around for ages, looks kinda oldschool but whatever. it will be looooow maintenance. we have a recipe already.

Im down to do migration work regardless of what we pick! Seems worth it to open up the whole docs situation to the rest of those involved.

Idk if it covers all the features we need but dokuwiki has SSO support, is file based, has a decent GUI and supports markdown. it takes a few plugins but it is feature rich. it's been around for ages, looks kinda oldschool but whatever. it will be looooow maintenance. we have a recipe already. Im down to do migration work regardless of what we pick! Seems worth it to open up the whole docs situation to the rest of those involved.

❤️ 1

kawaiipunk added a new dependency 2025-01-07 16:42:00 +00:00

#669 Do we need a Co-op Cloud single sign on solution?

~~decentral1se referenced this issue 2025-01-07 16:44:19 +00:00~~

Do we need a Co-op Cloud single sign on solution? #669

decentral1se added this to the Federation project 2025-04-20 06:03:06 +00:00

decentral1se modified the project from Federation to Documentation

2025-04-20 06:04:22 +00:00

decentral1se modified the project from Documentation to Federation

2025-04-20 06:05:07 +00:00

decentral1se moved this to Backlog in Federation on 2025-04-20 06:05:13 +00:00

decentral1se moved this to To Do in Federation on 2025-04-20 06:09:55 +00:00

decentral1se moved this to To Do in Federation on 2025-06-04 16:21:41 +00:00

Sign in to join this conversation.

3 Participants

Notifications

Due Date

No due date set.

Depends on

#669 Do we need a Co-op Cloud single sign on solution?

toolshed/organising

Reference: toolshed/organising#665