A bigger picture for device documentation
Over the last years I've been talking every now and then with @tmomas and other OpenWrt members about "user experiences" when handling firmware. After I suggested some radical changes in device documentation and firmware selection he asked me for a bigger picture. Here we go
This document tries to offer a status report on the user facing resources when
interacting with OpenWrt. It should be seen as a work in progress and suggestion
for extension and clarification are very welcome! Parts may be written in a mean sounding way, this is with no intention and will be changed once I'm aware of it. I highly value the work of the Wiki team!
Motivation is to improve things as both new and long-time users complained about
parts of the current implementation. The ideal outcome of a reworked
documentation and user experience would be:
Non tech-savvy router users feel confident in flashing OpenWrt on their devices,
resulting in a more secure Internet.
It then tries to determine requirements needed for this goal eventually propose
solutions, resulting in concrete To-dos.
Status
The following tries to summarize important user facing resources.
Downloading an image
Finding the router specific firmware is difficult for new and inconvenient for long-term users. The Downloads page first link clicked by a user forwards to the releases overview, which is confusing to say the least. If the user figures out that 19.07.3 is the latest release, which is not stated on the previous Downloads page, they end up at a the target overview. Again, confusing for someone new.
At this point whoever likely uses a search engine to end up at a device specific page.
As a random example, searching for a Archer C7 brings one to this page, which stores the link in one of multiple tables, combines with other similar devices. Overall are the information on the website likely overwhelming for non developers. The specific SoC or WLAN Hardware or CPU MHz are unlikely of direct interest for a common user.
As the page contains information for multiple devices at one, it is not trivial to parse which information is important for which device. Important information are likely missed due to the amount of information.
When choosing a random other device page, the article structure is likely different, either in amount of devices covered in the page or amount of in-depth information.
Keeping software up to date
OpenWrt tries to, but does not yet fully follow a 6 month upgrade cycle. This means, unlike for other distributions like Ubuntu, there is unlikely a feel for there must be a upgrade soon. Due to the lack of a announcement mailing list, regular users may miss new (service) releases and keep running outdated (and probably vulnerable) software on an Internet facing device.
The upgrade process itself involves again the identification of the correct image. Which means a X-Mas flashed router isn't trivially updated by its later users.
Software overview
OpenWrt offers a package overview both within the Wiki as well via CSV files. It show the package version within the latest release, no snapshot versions are covered.
Hardware suggestions
The table of hardware suggest to avoid devices with only 4MB of storage and 32MB of RAM. Consumer relevant information like dual-band, USB ports or WiFi standard (ac, ax, etc) are not easily visible. Looking at the per device overview gives a lot of information which is partly relevant for developers only, empty or wrong.
While there is a list of recommended device no complex search masks are available. The table size requires a lot vertical scrolling.
Device specifications
As mentioned before a per device view exists while a more complete overview exists at wikidevi.com or it's mirror/clone wikidevi.wi-cat.ru/Main_Page. These information are valuable but not embed-able in our views due to a lack of API. If all wikidevi clones die, all these information are lost.
Requirements
This sections tries to write requirements for a better user experience.
Data availability in machine readable formats
All stored data should be available in machine readable formats to allow downstream projects to develop their own tooling. This includes device information, package information as well as image/artifact information.
The data should be available in JSON and CSV if applicable.
Community edit and reviewable
All data shouldn't be maintained by a small group of people with privileged access, but everyone in the community. To allow a transparent process changes should be reviewable like Git Pull Requests on GitHub/GitLab.
Solution proposals
Here is a list of possible solutions, none of them is complete. Also the combination of the solution is point of discussion.
Firmware wizard
@mwarning is currently building a firmware wizards with a clean interface to easily find firmware images. Additional information could be shown, either hardware specs or installation steps.
OpenWrt JSON
The openwrt-json repository downloads available packages and stores them in JSON format, allowing tools like the firmware wizard to load package lists. The files manifest.json contains all information as provided by the current OpenWrt package overview. These JSON information could therefore also be rendered to a static website.
OpenWrt devices
The openwrt-devices repository converted the OpenWrt table of hardware to YAML files. These files are both human and machine readble and could be rendered to a Wiki like device overview. By using templates we can be DRY (don't repeat yourself), meaning we don't write 50 times the same 5 steps for installing TP-Link devices, but put it into a template. The page could look like the following screenshot, which is a recycling of the LineageOS website. We would obviously use something else, but it should give the idea.
Automatic upgrade selection
A proof of concept script automatically downloads multiple JSON files containing information to existing upgrades and images. This would allow a LuCI integrate where the user installs an upgrade via a single click.
To-do
Please share your thoughts. I'll update this post with a changelog.
?
