OpenWrt Forum Archive

Topic: Update on improving the OpenWrt wiki

The content of this topic has been archived on 16 Mar 2018. There are no obvious gaps in this topic, but there may still be some posts missing at the end.

The OpenWrt documentation initiative is slowly but surely moving forward. As we move forward on trying to improve the documentation of OpenWrt, I wanted to highlight some tasks you can help on right now:

  • Guide on OpenWrt security: OpenWrt provides numerous security mechanisms but it's not always clear on which the best one is for the task. Working on this would give developers and image creators a sense of what each of the techniques are and when to use them.

  • lib/functions.sh reference: lib/functions.sh is used in important scripts through OpenWrt but it's undocumented. Let's document them!

  • Procd script reference: procd is great but its documentation could be improved. There's already a draft of procd documentation to start from so you're not  starting from scratch.

Don't hesitate to get involved even if you're not exactly sure what to do. Comment on the issue and someone will be happy to help you. Any improvements, no matter how small they may seem, are important and valued.

If you want to see other issues filed for the wiki, please visit https://github.com/prplfoundation/openw … ive/issues.

Also, don't hesitate to file new issues related to the wiki and documentation at https://github.com/prplfoundation/openw … issues/new.

valentt: that's great! Is there anything I can do to help you out?

One thing you might want to consider is explaining how to install via LuCI as well.

valentt wrote:

I started writing python wiki page [1] but maybe a more general wiki page for development tools would be also nice.

[1] http://wiki.openwrt.org/doc/software/python

This is a great start. A question I always have comes up when a page says, "XXX requires 50 MBytes of space". I *think* this is free Flash memory (not RAM)

It might be good to say someplace at the top of the page, "All the memory requirements mentioned in this page are for the available Flash/NAND memory. The size of your Python program will determine the amount of RAM that is required."

@richbhanover good catch, I updated the wiki to say "50MB of free space on flash storage". Please join in and make this and other wiki pages better. We all should be contributors not only openwrt users.

@valentt thanks for the awesome work! And I totally agree with you on contributing. I've been trying to organize all the efforts to improve the wiki together. @richbhanover is part of his effort and we're trying to improve the wiki in a systematic fashion.

We're documenting issues in the wiki and wiki improvement tasks using the Github issues at https://github.com/prplfoundation/openw … ve/issues. I'd also like to hear your thoughts on how we can all work together to improve the wiki.

Thanks,

Eric

Thank you for taking the lead in this project.  It's very much needed.

eshultz wrote:

One thing you might want to consider is explaining how to install via LuCI as well.

I am an experienced Windows user and previously used DD-WRT for about 7 years.  I have been using OpenWRT for about 9 months now. CLI & UCI are just way out of my comfort zone, though I can access putty and plug code as directed.  If I have to install from CLI I think I'll go back (and suffer) with DD-WRT.

While LuCi has it's problems, I think at this point it functions well enough in core that it deserves to be documented in a manual format that basically resembles the level of content one would get with a consumer router. 

I can live with out a wizard function, as there is a minimum skill set required to just install the firmware over the stock firmware.  A "Quick Start" should suffice.

What is more important at this point than a full blown manual is a document (preferably with screen prints) that identifies each field and it's function and some discussion about it's purpose and/or how to interpret the information.  Fill in fields are most important, but static pages also are worthy of discussion.

EG: Status=> System => System =>Time Synchronization
Enable NTP client
Provide NTP server

OK, seems simple enough, and I do know that the first will get the time from a time server for the router because I know most routers do not have a battery to keep the time.  The second is also on the surface intuitive, but the reality is HOW   does on use this?  I know most people never set up the time feature on their router.  They do not know they can or should.  If it defaults it's set to the manufacturers time zone.

The point is, if we want to increase the user base, it will be through Luci (which is not even really part of the product).  There is so much more even in core with LuCi than most other tools that "Joe Average" (like me) does not have a clue as to what it does.  Much does not even have a wiki, and if it does it's not in LuCi speak, it's in UCI.  Try looking up mms clamping.

The document should be a downloadable PDF, as we need to be able to satisfy the basic need to deliver the content when the user is not connected to the internet.

Best regards... RangerZ

A really good manual on Luci would explain many things which remain mysteries to me even after nearly 8 years of use of openWrt on dozens of devices (mostly as little computers--I know next to nothing about routers).

But a new manual on Luci would very likely be made obsolete in a very short time by the new version which is in the works, so no one is likely to take on the task of documenting Luci in the manner that you describe. I hope the new version will get the treatment you suggest.

The discussion might have continued from here.