search

prplfoundation / openwrt-doc-initiative

Repository for holding the OpenWrt Wiki issues tracker
ISC License
6 stars 0 forks source link

Fix wiki.openwrt.org top-level pages #13

Open richb-hanover opened 9 years ago

richb-hanover commented 9 years ago

As with the OpenWrt home page (see issue #12 ) the top-level pages of the Wiki need to be updated with the same spirit of confidence and helpfulness to entice new people, especially newbies, to give OpenWrt a try.

Currently, the wiki has many pages in the top two levels that are listed as under construction, haven't been updated in years, or have information of questionable relevance beyond historical curiousity.

Ordinarily, this is a clear sign that a project is on its death bed. If I hadn't known that OpenWrt had real legs, I would never have switched from DD-WRT (or even Tomato.)

The current wiki conceals the fact that OpenWrt is a major success.

My recommendation is that we make a quick pass through all the pages that are two clicks from http://wiki.openwrt.org and ensure that each page:

This won't take long, and will give us enough information to make further priority decisions.

richb-hanover commented 9 years ago

I'm going to take a crack at creating a new version of the wiki home page. (It's not editable by ordinary wiki members) and then post the URL to it here by the end of this weekend.

wwahammy commented 9 years ago

Awesome @richb-hanover, thank you very much! Is there anything I or anyone else can do to help?

wwahammy commented 9 years ago

Maybe this is overly simplistic but if you look at http://wiki.openwrt.org/doc/start, that feels more like what I'd expect the OpenWrt wiki homepage (http://wiki.openwrt.org) to look like. I mean, it needs some cleanup but it's organized somewhat already. Could we simply start with that as the beginning of the Wiki homepage?

zo0ok commented 9 years ago

@richb-hanover made a start page to discuss: https://forum.openwrt.org/viewtopic.php?pid=276602#p276602 I find that version a better starting point than http://wiki.openwrt.org/doc/start I dont know exactly why though. And the latter one probably contains links/things that should, one way or another be in the starting page.

At the same time: less is more ;) Lets keep it quite simple. Could we (@richb-hanover) merge the "other start" page into "his" start page, and then we can start taking away stuff (by just linking, or even removing links) until the start page is clean and simple enough?

wwahammy commented 9 years ago

@zo0ok I think @richb-hanover's start page is supposed to be the main (openwrt.org) homepage. I was thinking http://wiki.openwrt.org/doc/start would be the homepage of the wiki (wiki.openwrt.org).

I would agree that we need to highlight different pieces of content on both pages though!

zo0ok commented 9 years ago

Ahhh... I am just trying to be helpful and constructive when I should probably be sleeping instead ;) But since I have already been stupid, here we go again: does the wiki homepage and the OpenWrt homepage need to be different pages?

wwahammy commented 9 years ago

No need to worry @zo0sk! You're helping a lot!

richb-hanover commented 9 years ago

I see a couple competing goals:

  1. I agree that the Documentation page might be the best foundation for the top level wiki.openwrt.org. (The current wiki home page is appears to have the same goal, but lacks the conviction to say it.) That top-level page should lead the way for different kinds of people:
    • newcomers who have heard OpenWrt is cool
    • experienced people who want to find out about specific features
    • developers
  2. I don't know if there is going to be some resistance to changing the top of the home page and wiki, so I want to keep things familiar, and minimize the changes in format from the current. (I would agree that a good wiki home page could indeed become the openwrt.org home page as well).
richb-hanover commented 9 years ago

I have taken a stab at converting the wiki's Documentation page (http://wiki.openwrt.org/doc/start) into something that could be come the wiki's top-level page. I factored out the info into three sections:

You can review the first cut of this work at http://wiki.openwrt.org/doc/playground My mind reels at the amount of work that will be required for the Newcomer page. But that's OK - we have a good team here.

I'm going away for the remainder of the weekend. Please feel free to edit these pages!

richb-hanover commented 9 years ago

I have also posted the full set of OpenWrt documentation pages to another github repo: https://github.com/richb-hanover/openwrt-docs This is one way to see how our current set of pages fit into the three guides described above.

zo0ok commented 9 years ago

I think the Wiki Documentation page with its 3 categories is good. And I understand it is not the OpenWrt start page. Allt the docs that went to github in HTML format... I don't really know what to do with it.

richb-hanover commented 9 years ago

I created the github files simply to show all the documentation pages that exist in the wiki.

I have the sense that some of those pages could be valuable for one or more of the guides - just looking at the filenames of the articles was helpful for me to understand what kind of info was there.

wwahammy commented 9 years ago

@richb-hanover I like where this is going! I worry though that the top level wiki page seem a bit sparse. I'm not sure what should be added though.

Also I was off this weekend and part of last week so I didn't get this until now!

richb-hanover commented 9 years ago

Yes, my proposed top-level page for the wiki at http://wiki.openwrt.org/doc/playground does look a little sparse. That's why I said, "What Else?" at the bottom :-)

On the other hand, I have the idea that the three guides should direct people to most everything they would want/need to know, so my hope was to focus most of the energy toward each of those three guides. (NB - the wiki's old home page is basically a concatenation of the Newcomer's Guide and the Developer Guide. I had to collect a few items to flesh out the Experienced Guide.)

wwahammy commented 9 years ago

Oops, I totally forgot to get back to you on this. I think you did a great job honestly. The documentation seems much better organized like this than before.

wwahammy commented 9 years ago

I modified the table so that that there's a line break between the description of a guide and the line saying "Read the " with a link to the guide. I also bolded the line. I think it's a little clearer visually but if others don't agree, I'm cool with changing it back :)

richb-hanover commented 9 years ago

No, it's definitely better to have those links to the guides separated and bolded. Good catch!

I think the last interesting change I want to see is to shuffle around the info in the Newcomers Guide to be a straightforward guide that leads people from discovery, to reading the detail page, to installing the firmware, and finally to getting it successfully running and on the Internet, with LuCI, Wifi, etc.

The information is mostly there, but it's presented badly/in a poor order. Currently, it says, "Just do this." "Oh, and now do this." "Oh, and if you want wireless, do this..."

Fixing the top-level page, and preserving most of the specific words will get us started. Anyone hungering to jump in? If not, I'll put it on my list after the ToH/Detail Pages settle down.

Thanks!

wwahammy commented 9 years ago

@richb-hanover I've started a new issue #17 for the newcomers guide and I'll take a crack at improving it.

richb-hanover commented 8 years ago

I took advantage of the (new?) ability to edit :doc:start (the top-level Documentation page) to install the draft that we had cooking from last summer. Please check out the new top-level documentation page at: https://wiki.openwrt.org/doc/start

If you have thoughts or comments, just start editing (it's a wiki, after all!)