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:

6

I absolutely agree that dokuwiki is showing its age. Search is a big one, and the fact that it doesn't use Markdown is another.

But I feel the need to explore this statement:

What are the important attributes of a git-based workflow? What benefits would it bring? What would it protect against?

My take: I am an admin on a git-based website, and it's a pain in the patootie. Because each site update is a commit, people are reluctant to make necessary tweaks in the name of "keeping the commit history clean". (Use case: I recently posted a new page on the OpenWrt site. I needed to make 50 edits from my initial draft on 1 July to now. That's a lot of edits, but the page is really the way I want it now.)

Futhermore, a git-based site makes it hard to have a wide variety of people adding or editing information. Instead it concentrates the responsibility for updates on the shoulders of a small number of people - they may be experts overall, but they surely don't know all the details of every topic.

One of the strengths of the OpenWrt wiki is exactly the same strength of Wikipedia: people who happen to know something, and are willing to make / update an entry cause the totality of the wiki to improve.

Note: I'm not saying that the wiki doesn't need a roll-back mechanism to protect against mistakes or vandalism, just that we don't need the full power and glory of git to get there. Thanks for listening.

7

A git based workflow allows (IMHO) easier comparison of versions. Most "wiki" based solutions are limited are even no use at all once the text base is huge or if formatting is not handled well.

I see and understand your points /against/ git, but from my experience, once a (large) text is "settled" most edits are small. And a huge change is easier to track with git, like with long lived feature branches a huge edit can be done in separate and edits on the base can still be tracked.
(I use line based and word based diffs to read text changes and if users for instance try to put one statement/thought/sentence into a single line then it can be quiet nice and clean.)

No I don't thing so. 1) See gitlab and github WYSIWYG edtior. 2) Markdown should or could be considered a no-brainer 3) If someone is not "able" to use markdown or a git-based (web-editor) workflow... I'm not quiet sure if that person is "capable" of providing /good/ technical explanation and such to other users. I don't want to sound elitism but ... yeah don't know... but maybe I'm biased... But with the gitlab/github editors even non-technical users should be capable of fixing small and spelling mistakes and they could even comment on individual lines, or do "feature request" or submit changes as a merge request.... so, and that is maybe the most important point: changes can easily reviewed upfront.
My main point with git is that I think its easier and better in the long run, and it should be easier then the user account management of a classical wiki...

Thanks for your input and concerns!

PS: I'm still with my first coffee... just sayin' ^^