Smart wiki for documentation

[Mohammer5]

I've had some thoughts about how we could organize documentation.. It's just an idea that I'd like to dump here before I forget about it.

---

Current issues (that I can remember)

1. We're always discussing the issue that either we have docs in a central place, with has its up- and downsides, or keep it together with the repository, which also has up- and downsides.
2. We're also struggling with where to put documentation if it touches multiple areas, like documenting recipes that use the UI library as well as the app-runtime library

Up- & downsides of a central docs repository

Upsides

• We can easily link between different docs
• We don't have to worry about writing "interdisciplinary" docs

Downsides

• We can't change code & docs in one PR
• Code & docs can easily get out of sync as it's hard to keep track of what's been documented and what not
  • This makes it more difficult, as a PR reviewer, to ensure that docs are adjusted as well as the docs are being changed after the PR has been merged
  • Currently we handle this through Jira, so we have a solution in place, but we can see a lot of out-of-date docs

Up- & downsides of having docs in the individual repositories

Upsides

• We can have both code and docs changes in one PR
  • This makes it a lot easier to add a barrier to a PR as we can choose not to approve a PR that does not have adjust docs

Downsides

• We might have to create multiple docs update PRs for a single code change.
• It's hard to find all relevant places that cover the code / usage of the code that's been changed

My idea

If we used a wiki-like system, we would not have to implement a hierarchical docs system, as it'd be a referential docs system where we can point from any article to any other article. We could easily create as many "overview" pages as we want, as we'd simply have to create a wiki page with references to other pages.

But a regular wiki would introduce the same issues mentioned above when using a central repo for docs, so here's the acutal idea:

• We keep wikipages in the actual repo, they need to have a unique name / id
• Wikipages can link to articles of other repositories by using their name / id
• We use some kind of service (e. g. during CI) that checks if the links are working / not working
  • If the links are not working, a PR can't be merged
    • When changing the name / id of a page, the service will check if there is any other page linking to the moved page, if yes, we should be able to add "redirects" and the service automatically adds an issue in the other repository (or Jira) with a high priority so the link can be updated and docs don't get out of sync
    • When removing a page that pages of other repositories link to, the service will create a 404 page for the deleted article with a link to the PR that removed the docs until all references to the deleted article have been removed AND creates issues in the other repositories (or Jira) with high priorities to update the docs

This would allow us to

• have docs in the respective repository
• put interdisciplinary docs into a dedicated repo or into the service's repo itself
• respond to broken interlinking / references