Combine "Installing USB drivers" and "Using storage devices" pages?


#1

These two pages seem to cover nearly identical subject matter, with much duplication.

Would it make sense to combine them into a single, definitive page? Thanks.


#2

I'm not sure how useful it is to remove duplication. It's not code. Generic USB troubleshooting can be useful for things like this as well: https://lede-project.org/docs/user-guide/smartphone-usb-tether


#3

IMHO, duplication in documentation is a couple orders of magnitude worse than duplication in code (and duplication in code is bad) because bad documentation has the power to waste more people's time.

With code, a single (knowledgeable) developer must take the time to read through the duplicated code to look for subtle differences.

But with documentation, every reader - perhaps hundreds of far less knowledgeable people - must mentally diff the two pages looking for common threads/important items/gotcha's to try to be sure that they will succeed.

For example, these two documentation pages describe how to install USB drivers, and each describes an substantially different procedure. I often find the differing explanations so difficult to reconcile that I simply give up (or maybe resolve to come back some day), rather than bricking my router/leaving it inoperable/etc.

So, for common tasks, I believe it is always better to have a single well-curated page that correctly and concisely describes the procedure, instead of having multiple people write their own incomplete, or marginally correct procedure.

Finally, I do agree that the first page (usb-troubleshooting) might stand on its own as a reference for lots of pages. But it should link to the other page's installation instructions, and its headline should be changed, perhaps to "Troubleshooting USB Drivers", instead of the current "Installing USB Drivers".


#4

Most users will have one task in mind, and will go to the drives or tethering page. They are referred to the troubleshooting page if that fails. The troubleshooting page tells you about more drivers because that's probably what you need if the drives page failed.


#5

I now agree that there is a bit many USB storage related pages:
https://openwrt.org/docs/guide-user/storage/usb-drives
https://openwrt.org/docs/guide-user/storage/usb-installing
https://openwrt.org/docs/guide-user/storage/usb-troubleshooting
https://openwrt.org/docs/guide-user/storage/usb-drives-quickstart

I think at least the installing and troubleshooting pages should be merged. If nobody disagrees I will do it later.


#6

Take care of the backlinks: https://openwrt.org/docs/guide-user/storage/usb-troubleshooting?do=backlink