Bringing docs/wiki to a new tech stack

Talk about Documentation
1

I discussed some options with @aparcar today about the future of the openwrt wiki.

The technological status quo of the mediawiki is quite dated. We are looking for a way to use a better future proof technology for this.

Historically, the mediawiki has the function of 3 tools:

  1. welcome, releases, contact, links to important pages
  2. toh, devices, instructions
  3. user created docs, FAQ, recurring installation and development guidelines

@aparcar already drafted a new solution for the first part: https://aparcar.codeberg.page/openwrt-org/
(source is here: https://codeberg.org/aparcar/openwrt-org/ )
This looks good, is based on hugo (SSG) and is editable by the openwrt team, while everyone can make suggestions through a git-based workflow.

No. 2/3 should be user editable, and I guess that we do not want to rely fully on GitHub for editing.

For 2. the LineageOS approach mentioned in https://lists.openwrt.org/pipermail/openwrt-devel/2025-February/043774.html is quite good and has been followed here: https://aparcar.org/openwrt-devices/devices/tp-link_archer_c7_v5/ (source: https://github.com/aparcar/openwrt-devices ) - but does not easily enable editing by users.

For 3. we need a proper wiki for sure anyway.

Users

As the forum software Discourse does not provide an OIDC/OAuth2 endpoint (but rather can consume one), the login for the wiki must be newly created when migrating as we can’t really migrate the existing users either.

The decision on a way forward should be made in consultation of the community and wiki users. That’s why I am posting here.

Wiki-Software

Possible alternatives are https://docmost.com/ , https://www.notion.com/ , Wiki.js (https://js.wiki/) and others (feel free to suggest things).

I currently think that wiki.js would be a good solution, as it has a solid Git-based backend and therefore can be eventually used to store editable markdown files, which are then consumed by other tools (e.g. the openwrt-devices page).

I wonder though how large edit volumes are handled and if it suits for the size of OpenWrt project.

Current Tweaks in DokuWiki

Unfortunately, there are many tweaks in the current openwrt Wiki:

  1. Indexes are automatically created with scripts (migration or replacement needed)
  2. placeholders for warnings and notes are inserted into other wiki pages (not possible in wikijs)
  3. various tables can be created from ToH and are embedded into the articles (maybe possible customization https://github.com/requarks/wiki/discussions/6506 )
  4. scripts automatically update all occurances of e.g. latest release links
  5. …

Do you see other things/requirements to a new solution which must be respected?

What do you think of splitting up representation from the dokuwiki web page?

2

I'm pretty much fine with any of the choice, but one thing that needs significant work is the search functionality.

The current search is truly terrible, you get 98% ToH docs when you're searching for, say, config file syntax, making it pretty worthless. If we had a better search engine, that would make life so much easier for everyone.

3

I’d like to put an emphasis on the explorative nature of this. Nothing is decided and it’s specifically important to incorporate the opinions of both project members and active wiki authors. I found it easier to discuss when showing alternatives, so I created a bit of a demo. However this is by no means the final nor approved version.

4

First of all thanks to @aparcar and @fmaurer for taking the initiative.

I, too, would like to see a next level of the documentation.

I can't stress enough that we need a git-based workflow.

What I'd like to see in the next gen documentation, besides

  • the technical and hardware low level specs;
  • the user facing install instructions and device specifics;
  • software or package documentation (how to use; how to configure; option references)
  • the current recipes (dump ap; various ipv6 setups; ...)

What I'd like to see is in addition are "branched" recipes or setup.
Most recipes are to narrow in my opinion and lag a good general explanation so users can easily adapt. By "branched" I mean that there could be multiple documents covering the same thing slightly different.

We should also spend some time reading documents back and forth, till we find a good "ordering" of documents, like with the current building openwrt section.
I think it's highly confusion for new once not only to decide if the user needs to build (compile) the source, or if the image builder just suites enough...

What I'd like to see no longer:

  • Hacky one-shot uci scripts, because these are blindly run by new user
  • If uci-scripts are used, then these sections should be shown as config stanza sections, too

Just my two cents during the first coffee.
Besides that: GO GO GO!! :partying_face:

5

I fully agree with that :+1: