I'm starting an initiative to improve OpenWrt documentation. I think we all agree documentation is an area seriously lacking for OpenWrt. I believe this is discouraging interested developers and companies from improving OpenWrt and participating in the community. It's often hard to understand how to get involved, how to test your changes and what tools are available to help you. I've talked with members of the core team, including Felix Fietkau and Imre Kaloz, and they’re supportive of this effort.

For those wondering why I’m getting involved, I’m doing this as part of my job. My name's Eric Schultz and I’m the Community Manager at prpl Foundation; a non-profit open source association. Our members use OpenWrt and participate in the community and want to make OpenWrt as successful as possible. I plan to dedicate a significant portion of my work time participating in this documentation project.

We all know there is documentation that's lacking or needs reorganization but we might have different changes we’d like made. So I want to start by asking some questions:

What do you specifically think is missing? What, in particular, needs improvement?

We can look at this like an "issue tracker" for documentation. I’ll answer these questions too and then we can go from there. I hope to work with lots of you on this; let's make OpenWrt even better!

Eric

A few areas that I think could be improved are:

* more comprehensive homepage for the documentation (http://wiki.openwrt.org/)
* references for important APIs, such as for procd (I've done an initial draft of this), lib/functions.sh and others
* tutorials for building OpenWrt in various configuration and testing, particularly using QEMU and other VMs.
* documentation should be "versioned" so it's clear whether it is up to date or needs to be tested against a new version
* Guide on the OpenWrt source tree. It should include a description of what's in the tree, how and why one would modify the tree and how the source tree corresponds to the compiled device output tree
* Guide on OpenWrt security. OpenWrt by default uses root for most services but there are ways to improve security for services while still fitting into the OpenWrt ecosystem. The guide should explain features like StackProtector, running a service as a less privileged user, OpenWrt jails, LXC. There should be a discussion of the pros and cons of each so developers have figure out what is best for their purposes.

Nice to see that we are getting backing regarding OpenWrt improvement!

Welcome, Eric!

IMHO the main task in improving OpenWrt is organization:

- What shall be improved?
- How shall it be improved?
- Who does the job?
- How is the status of the improvement(s)?

- There are already many proposals regarding the "What", but they are somewhat scattered in different threads; hard to keep track of.
- Also the "How" is discussed in different threads; hard to keep track of.
- "Who" does the job: The one who feels like improving it; no "mentor" (?) for a device, who keeps statusinfo and other technical data on the device page up to date and the device page in shape and structured.
- "Status" tracking: none; people get engaged, improvements are begun, interest goes down, page stays in half finished shape -> orphaned -> nobody keeps track of that

What, How, Who, Status: Discuss here in the forum, then pin down the destilled result of the discussions in the wiki (nobody wants to read through 250 postings for finding an answer ; users are willing to help, if you only show them how to help the right way).

OK, enough unstructured thoughts for now.

Let's start the improvement!

P.S.: "Chaos Calmer" can also be read in the context of the OpenWrt Wiki: Calm the chaos in the documentation. Nice

Edit:
Some threads regarding OpenWrt improvement:
OpenWrt Wiki – Maintenance: https://forum.openwrt.org/viewtopic.php?id=44998
Improve the Wiki Table of Hardware: https://forum.openwrt.org/viewtopic.php?id=56521

(Last edited by tmo26 on 30 Apr 2015, 20:09)

I am wondering how and if we can enable some mediawiki-like talk pages.

E.g. I did a cleanup of the TL-WR1043ND page a few weeks ago, and it has all been reset. Surely someone must have requested it, but there seems to be no way to discuss it. And the page is a horrible mess once more.

There has been an unplanned 'reset' some months ago, IIRC.
Server crash, no recent backup, some weeks of editing lost. Or something like that, I don't know the exact reason.

I think it was after that, but I'm not too sure...

A talk page would be nice though, or some place to discuss edits, to see what other people think about proposed changes.

Clean up of the various router pages. They are kind of chaotic.
The Table of Hardware improvement project is going very well but I'm sure could use some additional help.
More tutorials - at least for the most common things people do with routers that are not installed by default (or maybe even things that are).
Links to "community builds"

Would love to see the prpl Foundation commit some resources to improving the OpenWrt experience for new users beyond just documentation. The GUI could use some simplification and probably an initial setup wizard. Alternatively a simple and advanced interface would help. The design of the package manager could be simplified to something similar to FreeNAS plugin setup - just on/off buttons for the most common things. I have outlined some of these ideas in another thread:
https://forum.openwrt.org/viewtopic.php?id=54056

Excellent! It's pure serendipity that a number of people have had the same idea at roughly the same time. As we speak, others are cleaning up the ToH/Supported Devices page to make it easier to approach OpenWrt. They're over at: https://forum.openwrt.org/viewtopic.php?id=56521

But although a new ToH and improved documentation will be immensely useful, they are far from the only thing that needs work.

We need to change our perception of OpenWrt. At one time, OpenWrt was a techie's plaything, that only a techie could love. If you worked hard enough, you could get it going. Probably.

But now I believe that OpenWrt has graduated. It's made it. The Barrier Breaker release has turned the corner, and we should crow about it, trumpet it from the highest tower, and let the world know that OpenWrt is easy, powerful, reliable, and safe to use.

Yet as I read the home page and the wiki, the top-level pages all contain warnings, provisos, and caveats about things that are under construction, or that might not work. This would scare away any sensible person. Look specifically at:
  - http://openwrt.org
  - http://wiki.openwrt.org/start
  - http://wiki.openwrt.org/toh/start
  - and a number of other pages linked from them

We need to change those top-level pages (and then the rest of the site's pages) to tell the story of OpenWrt. They must welcome new people. They must let people know that OpenWrt is easy to use, and inspire confidence that most anyone can succeed.

I come to this project after three years of working on CeroWrt and maintaining its web site. We used OpenWrt as a platform for solving Bufferbloat. OpenWrt was an enormous help, providing a stable platform for our research. And the best news is that we've pushed all the good stuff back into OpenWrt. Now I'm switching to OpenWrt because I need a stable production router that isn't bufferbloated.

So I'm in. I'm willing to help. How can we move forward?

Excellent eschultz!

I will be straight forward: is it your intention to improve the documentation on the current wiki, or are/would you considering launching a new documentation platform?

I would be fine either way.

As I see it, the most important thing is to improve (clean up, add, review, reorganize, update, find ownership) the information (regarding of technical platform). A lot can be done with the wiki!

At the same time, sometimes a clean sheet is good (to not drown in old details). I think we need to consider 1st-page and wiki-navigation from a clean-sheet perspective, even if we end up just transforming the current wiki to a new structure.

There are weaknesses of the current platform(s):
- table of hardware (filter, search, sort, limit columns)
- tagging is not updated/consistent, and does not really "work"
- developer site, wiki and this forum live separate lives (with manual links between them)
   (imagine if the wiki "automatically" had links to the correct firmware builds for each hardware, and it was possible to discuss/comment directly)
- for documentation/support purposes it would be valuable to have data on acual usage/installations of OpenWRT on actual devices, and data on the problems people experience, not obvious how to do that with current platform
I dont really care, but in 2015
- the documentation could be "more social"
- the documentation could be more modern-looking/visually attractive

The worst thing that can happen is that a separate documentation project is initiated, that it gets stuck in technical details, that it requires much effort, and that in the end we have an old wiki and a new something, that both are equally incomplete, and nobody knows where to look or where to update. That is not going to happen or course.

I think it could be good to discuss this and come to a decision, so all efforts go in the same direction.
Perhaps very little discussion is needed, and it is completely clear that a new platform is out of scope, but that is also good for everyone to know.

I have (as most of you have seen) gathered information from the current wiki to present it in a new way:
  https://dl.dropboxusercontent.com/u/906 … index.html
I think this kind of "tactical" solutions can support improving the wiki or even complement it in the future.

In order to keep the links together:

Some threads regarding OpenWrt improvement:

• OpenWrt Wiki – Maintenance: https://forum.openwrt.org/viewtopic.php?id=44998

• Improve the Wiki Table of Hardware: https://forum.openwrt.org/viewtopic.php?id=56521

• Suggestions for making OpenWrt more newbie friendly: https://forum.openwrt.org/viewtopic.php?id=54056

Glad to know other folks are interested!

I'll just summarize what I've read so far and respond:

• No clear ownership of the documentation or portions of the documentation - I second this. Ideally, we'd have a documentation team. Each person could have particular responsibilities, organize a section, etc.

• Table of hardware needs improvement - Clearly. At a minimum, @zo0ok's work seems great! That would help a ton.

One question long term would be management of the actual pages detailing support for various routers. We might be able to get a bit of support from some of prpl's current or future members to address those for their own hardware but I don't really know.

• a place to discuss edits - yes, definitely. I wasn't sure where the best place to have this discussion even was at first. Are the forums the place? Or is somewhere else better. Talk page? Using a bug tracker like Github issues?

• a place to track progress - how do we know what has been accomplished and what need to be done? Is the forum the best place or should we try something like a bug tracker? I think answering this problem is critical because it's a primary way to recruit new folks into the OpenWrt documentation community. As @tmo26 said, people are willing to help, they just don't know what to do!

• homepage needs to be welcoming - I think this is partly related to organization. If we organize the documentation properly, with references, guides and tutorials for users, packagers and developers, this is very solvable problem.

As for whether we start from scratch or use the wiki as is, I want to do whatever we think would get more folks involved and come up with the best result. prpl has a wiki (MediaWiki) and forums (Discourse) if we'd like to move any of the work there. I don't want to do anything too technically complex or custom of course. One potential issue with the prpl wiki though is that the OpenWrt wiki is under a license (CC-BY-SA-NC) which isn't compatible with prpl's wiki license (CC-BY). It's a surmountable problem but there's some friction there from that.

I think the first place we should start with is decide:

• what the scope of what we want to do is? - Do we start over? If so, where do we host our work? Should it be a wiki where we have a talk page?

• how we organize and document our work? - Is this forum the proper place for general discussion? Should we use an Issue tracker? Do we want clearer responsibilities for particular areas?

What does everyone think? Also, does this cover the main questions we need to decide immediately?

(Last edited by eschultz on 4 May 2015, 17:41)

Good summary eschultz! This forum is missing a "Like" button so people don't say anything when they approve, which can be confusing.

You should have seen the Table of Hardware 2 months ago Now after all work tmo26 put into editing it looks much better.

As I see it now... it is higher priority to find a form to discuss/track changes/improvements and organize the work... than it is to anything radical to the wiki.

Even better: Look at it today. "Wired ports" column... uuuuhhhhh a pleasure! ;-)
(That's the little Monk in me *g*)

zo0ok, we're on the same wavelength. 100% agree.

- scope: Nope, don't start over. Apply http://en.wikipedia.org/wiki/Kaizen instead (you only nead to read the intro, not further). Short form: Continous improvement in small steps, rather than big steps.
Lets make one step after the other: First define, what needs to be improved in what way, then check if this can be accomplished within the current wiki.

- Issue tracker could be helpful. Alternatively more structured discussion here in the forum, i.e. separate threads for separate topics of improvement.
I created http://wiki.openwrt.org/discussion/improvement as a preliminary portal page or melting pot regarding OpenWrt improvement. Only to give it some structure.

What would be needed to implement an issue tracking system for the OpenWrt documentation (either separate from the already existing openwrt development tracking system or included in this as separate cathegory)?

Some afterthoughts: At first, before the issue tracker, it would be helpful to get people involved to improve the device pages.
More detailed: Acquire volunteers that feel dedicated and knowledgeable enough about a specific device to keep the device page in good shape, i.e. keep information updated (fw-image-urls, supporthistory, pictures, errors, caveats...).

While the whole community can edit most of the wiki, there's no single person that really feels dedicated to a device and keeps an eye on it (and on the device page in the context of the whole wiki, i.e. common structure for all devices).
There's no "In case of errors on this page, please report them here: https://forum.openwrt.org/viewforum.php?id=17 or contact wiki_improvement@openwrt.org or .... $somethingcompletelydifferent."

Get a community member behind each device, who reviews the content regularly (3/6/12 Months / with each major release) in regards to structure and up-to-date content.

I think we should also discuss a standard template for device pages, that would help for a more uniform layout, so people can browse them more easily?

And provide some handy code snippets somewhere, like expandable sections etc. Standardise the layout.

Base for discussion:
http://wiki.openwrt.org/meta/templates
http://wiki.openwrt.org/meta/template_device

re: Editing the top-level OpenWrt.org pages

I asked Gregers Petersen (glp at openwrt dot org) how people could get changes incorporated into the top-level pages of OpenWrt.org and the wiki.

His suggestion was that, normally, those top-level pages are handled by core-developers. He recommends that we put together a specific proposal, which he will present to those developers.

re: How do we proceed? (My thoughts on several of the topics discussed in this thread...)

I recommend a lot of hardware and software to friends and professionals. My reputation is bound up in the quality of experience that people have. I really like OpenWrt, and the power, capability, and simplicity that it offers.

My over-arching goal for OpenWrt is that I feel comfortable saying to a modestly-skilled person, "Oh, you want a good router? Just go to OpenWrt.org and you will see how to install new firmware that will work *way* better than your vendor's stock build."

This implies a few things:

- The main OpenWrt.org home page should let people know they've come to the right place. People should get the notion that "OpenWrt Just Works", that they can install better firmware in their existing router, or if they want to replace it, then here are suggestions...

- There should be a clear path (needing only two or three clicks) that gets them to a) the firmware for their router, and b) the instructions for installing. And people should be successful a high percentage of the time (90%? 95%?) using the instructions.

- Visitors want to feel comfortable that they can get help if they have trouble/questions. The forum's pretty good, but it would be nice if people succeeded a higher fraction of the time, so they didn't have to ask...

Is this a good goal ("OpenWrt Just Works for Newbies") for the project?

Based on my desires above, let me also say:

- Let's improve what we have. The bottom-level pages (the ones that can be edited by people who have the knowledge and care to share) are in reasonable shape. We need to update the top-level stuff to be more helpful.

- We definitely should have a template for a perfect "Device Details" page.

- I am pinning a lot of my hopes on the Device Details pages linked off the ToH. I want to steer people toward models that have a link to firmware and installation instructions because (presumably), they have been tested to be accurate.

- As a corollary, I have the hopes that we can encourage OpenWrt wiki members to maintain and upgrade the device details pages for routers they own. The work that @tmo26 and @zo0ok have done is spectacular, but I don't want it to become a full-employment act :-)

- Finally, I believe nearly all the other pages in the Wiki are secondary. (Mind, they're critically important to the project.) But the audience for those pages is already familiar with OpenWrt and/or its concepts. Let's not distract new people by discussions of building OpenWrt, source tree, APIs, or other details that geeks need to know about. (There can always be a "For Advanced Users" section on any of those top-level pages, but new people should be able to identify that they don't need those on day one.)

Thank you for your efforts.  I think this is a great idea.

One of the areas that needs to be improved is the firewall documentation, especially for the changes related to fw3.  I don't think there is even anything on the what or why of fw3 on the wiki.   In particular what is needed is more information and examples about how uci and the firewall interact.

A good starting point would be some common examples.    There are some examples in the /rom/etc/config/firewall, that get overwritten so I think many people miss them.  These mostly cover opening some ports.  These should be added to the wiki with a little bit of docs.

I would also like to see:
* Blocking some specific traffic both for ingress and egress  (example: prevent: MS Windows RPC traffic from coming in or going out of the WAN port.
* logging when specific things occur (example: log connections to ssh port)
* How to use firewall.user in conjunction with fw3 zones, and/or uci interfaces.   In other words how to add rules to firewall.user without having to make it specific to each router.

Also, I think there used to be more information on hardening/securing the router beyond the default configuration that is no longer linked to the current pages and may also be out of date.

Thanks

Great stuff everyone!

re: issue tracker - I think using Github issues would be the easiest and most straightforward. We can document the problems and work together on solutions. It won't clutter up the main bug tracker and it's a tool that lots of people are comfortable with. We can also easily connect it with tools like OpenHatch for highlighting OpenWrt documentation tasks. Unless folks feel this is a bad idea, I'll set it up on on the prpl Foundation's Github account and put in some of the topics already posted and then post the link here.

I think it makes sense for us to use this forum for general announcements, discussion on organizing ourselves, recruiting new participants and more.

In general, I think ownership of specific device pages is a good idea. I'm not sure really to start with that. Maybe it'd be best to have people here take on some of the device pages so we have some solid examples of what device page "ownership" entails? Or should we recruit some volunteers first? I'm open to ideas on that.

Thoughts?

I think this makes sense. I can volunteer to pilot-own the TP-Link WDR4900 (since I own such a device).

I can volunteer for the DIR-505 (since I own several of them).

@richbhanover - great goals! I do think the developers could do some things to improve the newbie experience on the actual firmware side, but improving the documentation in the ways you describe would also go a really long way.

A really clean details page is also critical IMO. There's too much junk on a lot of them right now. I would recommend one sub page per device that includes boot logs, teardowns, serial pinouts, etc. The main details page should focus on installation of openwrt, any quirks to the openwrt install/configuration for the specific device, the basic specs, and recovery mode (if one exists).

(Last edited by drawz on 6 May 2015, 02:08)

One thing I think could be improved is the theme, a Bootstrap 2 theme matching LuCI would be really nice.