@richbhanover & others already posted great goals

- Keeping old ("outdated") Information in the wiki might be important for some people.
At least in forums there are many ppl still asking for advice/support for AA. I have moved some old SDK/Buildroot info to "<pagename>.old" for that reason to keep it archived but separated from current information. Keep language simple & with warnings. (Chinese users)
- Provide "new" information before release (at submit) - generate "placeholder" pages.
- Much information is outdated and should be reviewed/retested. This takes a huge time especially if it involves compiling, testing on devices (you have to buy these or you have some devices "laying around") and searching (linking) upstream documentation and filing bugs/changing packages. (example: http://wiki.openwrt.org/wiki/bluetooth.audio done by me)

- Make pages easier to read. Divide pages more clearly. 2 - maybe 3 information "tiers" : normal user pages("Howto"), background info and developer pages ("techref").

- Cleanup:

I already merged the Howto and Recipes pages since they were basically the same (recipes only had wireless network stuff while the howto had all other stuff) and tried to divide that into sections for advanced user/topics that require more computer knowledge.
There is still other stuff that is either in "TODO" ( http://wiki.openwrt.org/doc/todo ) or in the "oldwiki" namespace that needs to be reviewed for "ages".
Its unclear if a better wiki pages will result in less people posting the same questions about network/flashing in IRC or forums because some people do not search first before they ask questions.

- Developer TODO lists
There was a discussion with some devs in IRC about a possible todo list/starting point for developers wanting to code in the wiki. I remember that there was agreement that it might be nice and could hold/buffer the trac/ticket system "whishlist" that OpenWrt indirectly has (most famous: Hardare NAT & other closed tickets). But this would have to be managed very strictly and might be prone to edit wars.

(Last edited by zloop on 6 May 2015, 05:12)

All,

I've created a basic issue tracker on Github at https://github.com/prplfoundation/openw … ive/issues. I've tried add issues for all of the topics that have come up in this conversation. I've also added some basic instructions in the main readme at https://github.com/prplfoundation/openw … initiative (we'll have to add those to the wiki). If everyone feels solid about this, I recommend we start adding issues and discussing topics there as appropriate.

@zloop: I agree a lot about what you said regarding information tiers. I've found that Jacob Kaplan-Moss' article Jacob  https://jacobian.org/writing/what-to-write/ describes the tiers of documentation very well. Here's how I summarize them:

Tutorials illustrate a basic workflow from start to finish. It hand holds the reader through steps. There shouldn't be any confusion over what the reader should be doing.

Guides involve a deep dive of a topic. They're often cross cutting concerns (like security) which cover multiple areas and deal with conceptual topics. Less guiding but examples of usage may be appropriate.

References are lower level and meticulously describe APIs and data structures.

High quality documentation requires all of them so people in different levels of experience can get access to the knowledge they need to participate.

---

Also, perhaps we should start a wiki page of the people "volunteering" for to adopt the documentation for each model?

Yes, please.
Something like https://dev.openwrt.org/wiki/platforms perhaps?

I want to help newbies figure out what is current, and what is old. Heres's a proposed plan. (In the items below, "we" means the relatively small set of people who're reading this thread and willing to contribute.)

- I agree we can focus our attention on the broad-based pages that eschultz pointed out in the github issues at https://github.com/prplfoundation/openw … ive/issues

- I love the division of documentation into Tutorials/Guides/Reference, and we can look through pages of the wiki with that in mind.

- We should ruthlessly mark top-level pages/Howto's/etc that have not be updated for BB, or that have "Under construction" tags older than 30 days with "This page has not been updated, and may not contain current information."

- I absolutely believe that we should update the devicepage for models that we own/use. The "Updating ToH Page" thread lists the standards we should expect, and most importantly, the "summary statistics block", for example, at the top of http://wiki.openwrt.org/toh/d-link/dir-505 (NB I own Netgear WNDR3700v2's and WNDR3800's, and a TP-Link Archer C7 v2, and publicly volunteer to update them - unless someone wants to snatch one from me.)

- But... @eschultz and @tmo26 I believe that we should leave old, non-updated device details pages as-is. This has a number of advantages:
  1) To update the device details page accurately, it must be done by a person who owns/has access the router. If you haven't personally tried it, you're just makin' stuff up.
  2) We can set expectations that anyone creating a new device details page (or updating it) should be sure to include the summary statistics block
  3) The lack of a summary statistics block is a cue that this page has not been updated, and new people will know that the particular router is not "popular"
  4) Leaving them as-is does not add work to this small team of people who care about the state of the OpenWrt site.

This plan uses the "power of the wiki" to improve OpenWrt documentation. A our team can focus on the most important top-level pages. We can also review the Guides/Howto's/etc. and make a quick determination which are dead/outdated (e.g. Under Construction since 2009) and mark them.

New people coming to the site then are guided through pages that have current, tested information. We can recommend that if there's no "summary statistics block" in a device detail page, then they should consider another router (or they can charge ahead, see if they can get it to work, and update it with their success...)

People who have written the (outdated) documentation may be unhappy to have their pages marked, but can be challenged to verify the information and update it. (At least new people won't be fooled into believing a document that's wrong.)

Does this make sense?

(Last edited by richbhanover on 8 May 2015, 03:34)

Yes! I guess it is within the "power of wiki" to do this in a way that we can easily list all outdated pages?
I am thinking (it is probably not a good thing to implement, but as an idea), can we add tags named "Outdated May 2015" or "Approved May 2015" just so we can easily see what is reviewed, what is not good, and what remains to review?

I was thinking of using tags for this purpose, too.

I'm suggesting a "lighter touch" by this team, because I don't know if we're expert enough to make definitive determination whether pages are approved or outdated. Instead of giving gold stars to the pages that are good, as a first cut, we can point out pages that are clearly no longer good (by objective criteria, not necessarily reviewing the content.) For example:

- I think it's pretty easy to find pages that say, "this page has been under construction since 2009" and replace that notice with "**//This page has not been updated recently, and may not contain current information.//**" (This applies to lots of low-level pages, but also a lot of top-level pages.)

- In addition, if the page has breathless prose touting the delights of Backfire or AA versions, but nothing newer, then it can also get "The Notice" at the top.

I'm *not* anxious to get into all the individual router pages. Here's where we can rely on individuals to update their favorite router details pages with the newfangled block of router info (we need a name for this). Newcomers can use the presence of these router info blocks as evidence that the page has been/is being maintained. (@zo0ok and @tmo26 have been working hard to make sure that info can be scanned to update the Table of Hardware automatically.)

Last thought: I'm not sure about tags - does the wiki have actual tags? I looked briefly, and wasn't sure that I saw any... And would new people see them?

(Last edited by richbhanover on 8 May 2015, 16:35)

http://wiki.openwrt.org/meta/tags
http://wiki.openwrt.org/toh/d-link/dir-505#tags

Tags are always at the end of the page.
I was thinking of using tags like "outdated" or alike only for admin purposes, so we can easily show all pages that need rework with a single click.

To whom can the issues be assigned?

Agree. The only purpose with "Approved" is to avoid that we all look at the same page several times to decide if it is outdated. We can have:
1) Outdated_May2015
2) Notoutdated_May2015
...or something...

My original thinking was we'd just allow anyone to put their name in the comments if they're interested.

We could use the assigning but Github issues only allows team members to be assigned. That means if someone new wants to get involved, we'd have to add them to the team and that just seems like a headache. In my viewpoint, it's just easier to volunteer in the comments and ignore the built in assigning.

Wait, then it's not possible to filter for issues assigned to $user (me)?

Hmmm... This is an interesting idea, but marking something as "OK" leads to a maintenance hassle in a year or two because the OK-ness may decline over time. For example, in 2017, what conclusions can we draw about a page marked as "OK" in May 2015? (I agree that marking something as outdated is useful. Once outdated, it will remain outdated until someone actually updates it.)

I would almost prefer that the team take a week or so, scour the site and mark outdated pages, then declare victory. The fact that some pages got viewed/checked multiple times isn't such a big deal - I think the "checking for outdated-ness" is a pretty easy task, and won't consume a lot of brain cycles.

We can then use interesting new events (for example, release of the final CC build) as an opportunity to go through the site, identifying new (un-updated) pages.

Hi all,
you may have seen a handful of changes by me - nothing more than syntax corrections. I'm currently documenting the Arduino Yun, however I was waiting until someone to the reigns of this documentation effort before jumping in with both feet.

A little background, I working on starting my own company that does robotic platforms (sort of chassis for robot builders). In the meantime, I must work on making money - so I do full stack mobile development. Right now I spend most of my time on the Arduino Yun forum, the phonegap, then bluetooth, then this forum. It's about to change. So here we go.....

Since I do automated documentatio (based on source code). I will ask which language are people most comfortable with. I can do PERL, Python, Bash, TCL/TK, Javascript or Lua (if I learn it). My favorite is TCL/TK, but I'm thinking Python, since it's widely preferred, but I'd like some opinions.

After that I'm going to ask where are all the source repositories. I'll start with the forest, then work the trees. (pun intended).

Jesse

Hi Jesse,

Thanks for the changes you're making to the wiki. Creating documentation from source code sounds quite interesting, but it's a bit off-topic for this thread. (We're focused on fixing the pages we already have that are outdated, misleading, and not targeted toward getting new people started on OpenWrt.)

I have taken the liberty of starting a new topic on the Community Documentation forum at:https://forum.openwrt.org/viewtopic.php … 57#p275757

Best regards,

Rich Brown

Hmmm, that's a problem I hadn't thought of. How about we change this and I'll set up a doc team which I'll just assign anyone interested to?

What's your Github username?

Same as here.

my github handle is the same.

Jesse
https://github.com/jessemonroy650/

@jessemonroy650 and @tmo26: I've added invited both of you to the doc team. Once you've accepted, you can assign yourself or be assigned to an issue

Related to the idea of tagging pages with some variation of an "outdated" tag: does anyone have experience using the searchtags syntax to get pages without a given tag? I've used the syntax in the plugin:tag documentation but it doesn't seem to do anything.

I think that's the main thing we'd need solved to actually move forward on the tagging.

quick comparison of https://dl.dropboxusercontent.com/u/906 … index.html and the output of

{{topic>64RAM -8Flash}}

shows OK result (forgive incomplete tagging).

Edit: Just noticed that searchtags do quite a bit more than the above.

Edit 2: http://wiki.openwrt.org/meta/playground#tags
Does that what you expect?

(Last edited by tmo26 on 12 May 2015, 23:35)

Thanks tmo26. I had tried that and I'm getting an empty result. If I go to http://wiki.openwrt.org/meta/playground#tags and use a negative like the "x86-64" tag and click Search and I get no results. I'm not sure why that is.

Tryout1:
+ wnic (2 devices, one of them with 802.11bgn)
- 802.11bgn (filter out that one 802.11bgn from above)

-> 1 result = correct

----

Tryout2:
- 802.11bgn (i.e. no positive filter)

-> 0 results

Seems that searchtags needs at least one positive filter.

That does seem to be the case. Any idea how we could get a list of pages which don't have the Outdated_May2015 (for example)? The searchtags and topic don't seem to help us here

I mean we could do it if we select every other positive tag but that seems a bit impractical and doesn't handle pages without any tags