Report problem link?

Talk about Documentation
1

As a new developer I have frequent need to refer to the wiki documentation, probably more often than experienced users.

Documentation is improving quickly, likely due in part to the 'edit' buttons.

I have found a number of holes in the documentation, but being new, don't have the information to perform an edit. Yet the information I have, the specific place in the documentation that requires attention, is valuable and should be preserved until an appropriate edit can be made.

I propose that the wiki edit buttons be changed to composite 'edit/report' buttons. And the resulting edit pages contain a "Wiki / documentation forum" radio button that affects the destination of the Save button. If Wiki is selected, the edit save button functions exactly as it currently does. If documentation forum is selected, it creates a new post here, where it can be evaluated and anyone that has the required information can follow a link in the post back to the original place in the wiki and perform an edit based on the forum comments.

Alternatively, in case the edit page cannot be modified, the edit buttons could be left alone but add a small help button right next to each edit button. That button could drop the user at a specific support forum relevant to the documentation they came from and prefill their post with a link back to that documentation page.

An example where similar policy has worked well is First Robotics Competition

An example of documentation holes: https://openwrt.org/docs/guide-developer/using_the_sdk

Obtain the SDK
You can either download an already compiled SDK, or compile it from LEDE sources. Compilation from source will be talked about more diffusely in the appropriate article.
The precompiled SDK is found in the same download folder where you find the firmware images for your device.
for example, this is the folder where you find firmware images of adm5120-rb1xx target, and the SDK is called lede-sdk-adm5120-rb1xx_gcc-5.4.0_musl-1.1.15.Linux-x86_64.tar.xz

There is no link to an "appropriate article". Even so, it is easy for a beginner to just compile all the tools in the source using make menuconfig. Assuming a user has done that(using info from a different article), this article should at least help a user get from post toolchain compilation to where instructions are common for a user who downloaded a standalone SDK. This article never even names the directory which contains the SDK. That is an important piece of missing information.

1 Like
2

I just looked at this page today; and made another thread for the missing information to be moved from the archive to the active Wiki:

3

It's not "being new" but that you shouldn't be expected to know the code or build system intimately to be able to understand it. Those types of things need to come from the developer(s) that know the code and its intents. Beyond the build system, there's the OpenWRT-isms like procd, ubus, and netifd, to name a few, that there isn't "alternate" documentation like "normal" man pages to refer to.

Even when such documentation is available, the differences between OpenWRT and "normal" distros aren't documented. Just today, a new (to me, at least) OpenWRT user, @chris5560, who seems to have a good understanding of Linux and Linux distros, was puzzled by the unexplained inconsistencies.

It's unfortunate that third-party documentation is better than that of OpenWRT itself. Take http://wiki.prplfoundation.org/wiki/Procd_reference as an example.

I'm all up for a "report" button. The $64,000 question is if the developers consider it enough of a priority to document their code in anything but its source, and keep that documentation current.

1 Like