Styling is not negotiable - it was requested to bring back the OpenWrt wiki "look-and-feel".
More specifically, the styling has already been negotiated as one piece of the entire merger process that also included admin privileges, commit privileges, procedures and policies.
what is the problem of keeping the Lede style ? modern and practical
2 Likes
Thinking over this again and seeing time running, I'm starting to think about going back to a much simpler plan (the one I had at the beginning):
- make OpenWrt wiki read-only
- make LEDE wiki read-only
- transfer OpenWrt wiki to LEDE servers
-- make archive available under oldwiki.openwrt.org (read only)
-- make writable copy available under wiki.openwrt.org (=basis for the merged wiki) - merge OpenWrt + LEDE wiki "by hand"
Your thoughts about which way to go are more than welcome!
Once we agreed on that, it shouldn't take much time to get the infrastructure set up.
what is the problem of keeping the Lede style ? modern and practical
This is what happens when C programmers are allowed to decide on style. One of the developers went as far as stating that the current look of Lede wiki is dated.
But they are the project owners, so they get to decide.
Once we agreed on that, it shouldn't take much time to get the infrastructure set up.
@tmomas
That's more or less what I had in mind too, and I'd rather start sooner than later.
To that I'd just add that whatever article we have in current LEDE wiki should superseed and obsolete its equivalent of OpenWrt wiki (maybe with some exceptions).
The rest of OpenWrt articles should be placed where they should belong in the current wiki structure, and I would like to give them some (nonvisibile) mark so they can be read and checked for consistency/relevancy later by me/you and others that want to help.
1 Like
OK, then we are on the same page.
My intention with proposing to take the OpenWrt wiki structure (instead of the LEDE wiki structure) was to break as little of existing links to wiki.openwrt.org as possible.
Why do you think we should take the LEDE structure instead? I'm not totally against it, but we should have a clear rationale to do so.
That's the first and IMO most important decision we have to take:
Take OpenWrt wiki + structure as basis for the new wiki
Take LEDE wiki + structure as basis for the new wiki
We could create a poll and let swarm intelligence decide, but then again, seeing the little feedback on the mailing list and here in the forum, I doubt that this will be a successfull poll with great participation. So in the end, I guess it's up to us.
The reason why I didn't just copy-paste the OpenWrt wiki over as-is but I gave the LEDE wiki its current structure should be obvious, but let's explain it for the sake of making sure everyone is on the same page.
In the LEDE wiki layout it is much easier to navigate and to find things, which I think is the main goal of a wiki. I always found the OpenWrt layout confusing.
I'll make a practical example: let's say I'm looking for setting up Samba share.
Something that we can agree is not exactly exotic and will be interesting for many people so should be in decent shape.
I'll write down my internal commentary to what I see in this voyage. I'll also write down mostly rethorical questions, I already know why most things are like they are because I've been around for a while, but a random reader will very likely not.
It's probably my own personal opinion of grumpy impatient snowflake, but should give you another point of view than your own, and that's good enough for this.
oooooo-------ooooooooooooooo----------------oooooooo
So let's start: I open the main wiki link
https://wiki.openwrt.org/
And right there I can tell you that the tree of links at the top looks much worse and is less attracting than the sidebar we have on LEDE wiki.
But anyway, here I can choose to go to "Documentation Overview", "Generic Basic Howtos", or maybe "Beginners' Guide to OpenWrt"?. And right there is the first issue, where did people place my article? It MUST be obvious at first sight (i.e. in the title), so at top level there should be only ONE choice ("documentation" link), not 3.
I open Generic Basic Howtos because it has "howto" in the name (and also basic, hoping Samba was deemed "basic" enough to be there).... and nope. That's openwrt-specific documentation, not for additional features. I actually did this as I don't remember the openWrt wiki layout so I guessed, I'm not doing this just to make it look bad.
Then I open the "Documentation overview", hoping that being "overview" means that all stuff is listed here.
Then the page I see is the one we also cloned in the LEDE wiki, and that page is ok (by itself). Since I need additional features and the Experienced user guides clearly states "Start here if you already have OpenWrt running on your router. OpenWrt has hundreds of optional packages that give you VPNs, VLANs, and other capabilities", then I strongly suspect that the guide I'm looking for is in there. Good and we can go on.
Then I land in https://wiki.openwrt.org/doc/guide-experienced which again splits stuff based on unknown reasons. What's the difference between "recipes" and "howtos"? Why are they kept separate?
And also links to what seems to be developer documentation below, "hardware", "adding support... ", what is this thing I want to share a folder on the network here, I don't care about my router's hardware.
Anyway, I click on Recipes and I get a bunch of tables where most articles are not sorted according to their function, nor there are titles nor anything helping me. What is "overviews" and what is "articles assortment" categories supposed to mean anyway? Is that even useful?
I can either read all descriptions of each damn guide or use the search function of my browser. That's a layout fail.
From the names I find "Set up a Server", that has this description Provide Web, FTP, File, P2P and other network services
Now, being an experienced user I see "server + file + services" and I guess that this might be what I'm looking for. And the page under it is decent for an experienced user and I can get to my article https://wiki.openwrt.org/doc/howto/server.overview
But less-experienced users might not think that Samba is a Server, and think the article they are looking for is "Filesharing overview" instead, because "filesharing" is more obvious than the above.
And clicking that what do we see? another great page where I can choose between "recipes" and "howtos" or "filesystems.network" and there are many "fixme" and other stuff that may be unrelated! Of course!
And if I click on "howto and recipes" I go back to the other page. Great. This is a pointless link. People have either breadcrumbs on the top of the page or their browser's own Back button for going back. (and on LEDE wiki they also have the sidebar, which is great at this)
Clicking on the "filesystems.network" I end up in a techref page https://wiki.openwrt.org/doc/techref/filesystems.network which more or less duplicates the filesharing paragraph of the https://wiki.openwrt.org/doc/howto/server.overview as it has links to the same articles but looks worse and is less obvious for normal users.
oooooo-------ooooooooooooooo----------------oooooooo
same thing, LEDE wiki. https://lede-project.org/
main page has a bunch of blabla I don't really care about but I immediately see a sidebar, and in this sidebar I see Documentation. Great.
I land in the documentation landing page https://lede-project.org/docs/start
which guides me to choose the User Guide (and also the name "user guide" is more alluring than "experienced user guide") the same way the other page above did.
(I don't see why having a list of all stuff by namespace below would be useful, but it does not really hurt anyway.)
And I get in the landing page for most user documentation.
Then I can scroll and read the titles (or use the table of contents to the rigth). Additional services (since all other titles are clearly NOT what I'm looking for), then the subtitles. NAS services (network attached storage): and then I have links with clear names like "SMB Samba share configuration (aka Windows file sharing). " that should help less-experienced users to decide.
And I got to the article I wanted. Like less than 1 minute, no time wasted going down the wrong branches of the wiki structure, no time wasted asking myself what the titles really mean.
Ok, the LEDE wiki has less stuff, so it can get away with its current layout while with more articles it might become more cluttered and harder to read. I don't know, if that will happen I'm going to split content again in other pages, or do something, but the same general idea applies, keep branching to a minimum, have obvious titles/names in links even for less-experienced users.
2 Likes
Another thought. I had always hoped that the merger might be a way to curate much of the (ancient) cruft from the current OpenWrt wiki into the new wiki. (NB: curate: verb: "select, organize, and present (online content, merchandise, information, etc.), typically using professional or expert knowledge.")
Instead of us taking on the responsibility of manually merging the hundreds of OpenWrt pages, I wonder if there's a way to preserve the old wiki (perhaps making it read-only) and encouraging current LEDE/OpenWrt folks to copy over the "good stuff" to the new wiki.
We would provide the guidelines (in the Wiki Contribution Guide) and let people use their expertise to make update. And of course, the old wiki would be read-only so it's preserved for all time. Thoughts?
2 Likes
No need to mention that, we all have this in the back of our minds 
Although.... good that you mention it!
Two approaches:
- Copy complete devicepages from old wiki to new wiki, do the cleanup afterwards
-> Gives functional wiki right from the start, cleanup will take long time - Initially copy no devicepages at all to the new wiki, but create new, cleaned up devicepages step by step
-> much work to do, will take long time (during which devicepages are only available via old wiki), but gives clean devicepages from the start
I favour 1), just to get things started and have a functional wiki. We should revive the discussion about how to "renovate" the devicepages.
Complete old wiki will be available read-only under oldwiki.openwrt.org.
I think the general wiki guidelines are not enough in the case of devicepages. We should provide a sample devicepage for guidance, otherwise we will end up with the same like today: Many different styles and different content, different order of content, ....
We have a broad spectrum of devicepages: From barely filled with anything more than the datatables, up to mega-pages with a dozen versions of the same model. The barely filled ones are easy, while the mega-pages deserve more attention and a plan on how to create a new page out of them.
Thomas, is it possible to:
- set automatic redirects (or just links) from new wiki to archive for all devices
- create "new, cleaned up devicepages" for select devices, disabling the redirect for specific devices?
That way information on all devices would be accessible from the new wiki and it will give an option to slowly migrate the content to the new formatting for the new/popular devices.
Automatic: No. Creation + removal of redirects would be manual work.
Hmmm... why go the hard way (manual search through the wiki) when there is a search function?
https://wiki.openwrt.org/start?do=search&id=samba
https://lede-project.org/start?do=search&id=samba
Quick results in far less than a minute.
Take wikipedia: Let's search for Henri Poincaré (mathematician + physicist).
- Go to https://en.wikipedia.org/wiki/Main_Page
- Where to go next? Mathematics or Science? Lets take science.
- Now we follow "People". OMG, no, that's not what we are searching for.
- Back to the science portal, we now try "Physics" -> https://en.wikipedia.org/wiki/Portal:Physics
- 1 minute up and down on that page... Still havn't found anything that could lead me to Poincaré. No, thanks, that's already taking too long, giving up.
Now lets use the wikipedia search function:
- Go to https://en.wikipedia.org/wiki/Main_Page
- Enter Poincare (mind the missing accent)
- Searchresult: https://en.wikipedia.org/wiki/Poincaré
- https://en.wikipedia.org/wiki/Henri_Poincaré
Found what we are searching for in less than 15sec.
Don't gte me wrong - I'm not advocating any wiki structure, neither LEDE nor OpenWrt. What I want to point out: Use the right tool for your job.
Luke, use the for... err... the search function!
We have to discern different usecases:
- If you are actively searching for something, use the search function.
- If you try to learn something that is completely new for you, use the wiki navigation as a thread that guides you through the learning process, step by step.
... and in page titles, and in page names.
This enables the use of automatic index creation like here: https://wiki.openwrt.org/doc/howto/index.by.subject
https://wiki.openwrt.org/doc/howto/index (alphabetical index)
Once these index pages are set up, all you need to do is create a new page with suitable pagename and you are all set. No need to add that new page to any other page, because the index takes care of that.
Such automatic index pages are certainly not the solution for everything, but they can be a great help in showing the available pages in a structured way.
Any automatism we can use lessens the need for manual interaction by admins.
Luke, use the for... err... the automatisms of the wiki!
Then you should be adding keywords to make sure that people searching in different ways can find what they are looking for. "samba" + "filesharing" + "windows shared folders" + "nas" + "whatever"
Or accept that a sizable percentage of people won't find stuff with search function. Really there is a reason if Google is a thing and Bing is garbage. They have smart algorithms that help people find what they are looking for, it's not just literal word search in a database.
While following a decent wiki layout will always work in finding what you are looking for.
Actually having the internal search using Google advanced search (search within the site) would also be better than whatever rock-bashing system the internal search uses.
Or you have a generic question, like "what can I do with openWrt" or "what can I do with networking in OpenWrt". Or the search failed (as you were using the wrong words, maybe you didn't remember the exact name, only the more generic topic).
Which is why Wikipedia isn't just a massive alphabetical list of articles accessible only by search. You start with a more generic question and reading it and learning/thinking about it you decide and travel through the internal structure and links and reach other places.
It's also interesting in its own right to just read stuff off wikipedia, but that's probably not the case for our wiki.
For this type of users the OpenWrt layout sucks as I explained above, even having a simple alphabetical list of all articles in the wiki would be more efficient than that.
Meanwhile, current LEDE wiki is perfectly fine for both such type of usage, while still working fine for the search function.
Which again for me makes a no-brainer to choose LEDE wiki layout for the new wiki.
For what purpose? Alphabetical lists won't help people that need a wiki layout to guide them, and will be even less useful for people using search function.
I'd rather not have automation added unless there is a very good reason to have it. Apart from weighting down the server for no reason, they might break or cause other issues (like that error I pointed out some time ago and you thought was a caching issue).
I don't mind doing this manually, it's not like moving an article to a list somewhere takes a long time, nor there is a massive influx of new articles. Saving like 10 min every month is probably not worth the risk of having this thing break and having to waste time troubleshooting it in inappropriate times (or migrate dozens of now-orphaned articles to a normal page with links).
And this is assuming we needed alphabetical lists at all, which I don't think is the case.
1 Like
Copy complete devicepages from old wiki to new wiki, do the cleanup afterwards
-> Gives functional wiki right from the start, cleanup will take long time
I also favor this.
re: devicepages
or maybe a third choice...
- Create a pre-built template for all devicepages, and append the old devicepage data (if it exists) to it. Although I would want to revise it significantly, the template could look something like https://wiki.openwrt.org/meta/template_device.
This process immediately adds value to the devicepages since the technical info about the device appears in a standard form (in those datatables), and suggests the right place to insert the relevant narrative for a "well formed" devicepage.
Appending the information from the original OpenWrt devicepage to the template preserves it. People who care about the device will be free to copy the relevant info into the proper place in the main template. A side benefit of this strategy is that it's clear to the reader whether there has been recent maintenance on the devicepage.
It also distributes the responsibility for updating/maintaining the device page to those who care/are expert with that device.
Thoughts?
1 Like
Personally I would like to see the wiki merge happen sooner rather than later, (same with the forums). I also lean towards the newer more modern LEDE look and feel, (but I care more about the information being clean and clear).
IMHO there is momentum being killed off the longer we put this off. The wiki's are in major need of some cleaning up and consolidating. I was personally given the run around with attempting to get an image of a device, (lede-project official site references https://lede-project.org/toh/start which points to devices in the OpenWRT wiki while https://lede-project.org/toh/views/toh_fwdownload seems to have the LEDE links). Things honestly seems to be a mess right now. (I would say the same issue with the forums).
I completely agree with having a device template as a standard, (information is useless if not presented in a clean and clear for the intended user).
I would also think that creating a new wiki and archiving and making RO the openwrt and lede-project is the way to go, (I would add Legacy Wiki LInks as part of the template to point to the RO equivalents).
Looking forward to having this cleaned up.
The underlying data of both pages linked by you is the same, therefore I wonder where you see a mess.
Apart from that: We're working on the wiki merge.
I'm on standby actually.
Did we reach a consensus on the layout or not? What are the next steps? You need any help doing something?
In that context: The OpenWrt/LEDE wiki pages for the various Lantiq xrx200 devices are a mess, including links to outdated out-of-tree builds, no way to find other devices from the same family, conflcting howtos and just general ouch.
I plan to start a few of them from scratch. Which template should I use, and in which wiki should I enter the data to make this easier for those who do the wiki merging afterwards?
I'm currently quite busy with other stuff, which leaves less time than usual for LEDE/OpenWrt. I'll try to respond more detailed this evening.