+- Kodi Community Forum (https://forum.kodi.tv)
+-- Forum: Support (https://forum.kodi.tv/forumdisplay.php?fid=33)
+--- Forum: General Support (https://forum.kodi.tv/forumdisplay.php?fid=111)
+---- Forum: OS independent / Other (https://forum.kodi.tv/forumdisplay.php?fid=228)
+---- Thread: [WIKI] HELP UPDATE OUR FAQs! (/showthread.php?tid=114103)
- Chris! - 2011-12-01
cool, still easy to embed.
- Ned Scott - 2011-12-01
Here's the very rough draft of our platform independent FAQ: http://wiki.xbmc.org/index.php?title=XBMC_all_platforms_FAQ
The old general FAQ has now become the "intro to XBMC" type FAQ at: http://wiki.xbmc.org/index.php?title=XBMC_FAQ
You might notice on the all-platform FAQ (and the iOS FAQ) questions are most often not formatted as questions. We found this actually makes it much easier to navigate the table of contents at the top because it makes the keywords stand out. It's a little strange, and there are a few times where putting it in question form is still best, but it seems to work really well on the iOS FAQ.
I based the sections on the suggested questions from this thread and ideas I had. We can change the sections or add other sections as needed. The "shortcut/anchor" link is there to help make it easier to link to questions when the "question" or title changes. In other words, use the shortcut/anchor link as a permeant link.
There are a lot of questions that will basically need a second page, either a new one or an existing one (which likely needs to be cleaned up ;) ) but that's also a function of the FAQ (to be a lead-in to other parts of the wiki, that is).
- Chris! - 2011-12-01
Followed your style in platform independent FAQ to answer the Add-on questions you posted (as i recently finished the Add-on wiki page).
I like the style.
Let me know if there's any prob with my implementation.
- Ned Scott - 2011-12-02
Looks great! I did do some tweaking, but that's just the nature of a wiki. Constant tweaking, improving, etc. Feel free to tweak mine or anyone else's stuff as well if you feel it needs it!
- Ned Scott - 2011-12-03
http://wiki.xbmc.org/index.php?title=Category:All_add-ons
using dynamic list creation and DonJ's add-on page creating bot, we now have a matrix-ish list of add-on compatibility on the wiki. Just for giggles.
- Ned Scott - 2011-12-03
New Online Manual TOC (main navigation for the manual) http://wiki.xbmc.org/index.php?title=Template:XBMC_wiki_toc
Some links are two clicks away instead of a direct link (like individual OS install pages) but any of that can be changed if needed. Any suggestions, comments, should includes, should excludes?
We also have a bunch of new stub pages like:
http://wiki.xbmc.org/index.php?title=SFTP
http://wiki.xbmc.org/index.php?title=WebDAV
http://wiki.xbmc.org/index.php?title=AFP
- Chris! - 2011-12-04
Looks good. Probably being Dumb but what does "toc" mean?
I was thinking it might be a good idea to have a "how to use the wiki" (but without obviously being a how to use a wiki type page) type pages so new users could explicitly be told where to look for information - sometimes a search ends up with very technical stuff.
- Ned Scott - 2011-12-04
pseudo7 Wrote:Looks good. Probably being Dumb but what does "toc" mean?
I was thinking it might be a good idea to have a "how to use the wiki" (but without obviously being a how to use a wiki type page) type pages so new users could explicitly be told where to look for information - sometimes a search ends up with very technical stuff.
TOC- Table of Contents
Hopefully between tweaking the Main Page, and adding additional navigation templates (like the Manual TOC) will help link topics and make finding stuff easier. Although wiki help pages are planned, and will include some of that "end-user" info. We're also looking at extensions for the MediaWiki software that will improve on the default MW search (which leaves much to be desired). I also hope to better separate what are "end-user" pages and what are more "advanced/developer" pages, in some way.
- Chris! - 2011-12-06
More as a note to myself, but have noticed frequent questions about os choice and the lumitations of each one. Could be another good wiki article.
Also, ned - have you thought about asking eskro and poofhairguy to convert their stickis in the hardware forum into wiki posts (as i saw you were encouraging users to post their setups in the wiki)
Cheers
oops, typed that on a phone - changed to poofhairguy
- Ned Scott - 2011-12-07
Sounds like a great idea. I'll be sure to poke them about it.
- j114 - 2011-12-30
Ned, I had a couple of thoughts on the wiki that I wanted to share. I am sure some or all of these things have been thought of, but for the sake of clarity and progress I wanted to spell them out. I've worked in technical support roles for a long time now, and one of the first things you learn is to cater to the lowest common denominator. Some people are (very) offended by this mentality, but it has been proven time and again that if you assume your user understands something that you have not spelled out for them, you are going to spend twice as much time dealing with their problems. Even learning this from experience, I often catch myself making assumptions that people understand the fundamentals behind a subject we are discussing in a forum (not just here), and it backfires on me all the time.
One of the biggest problems with any wiki, as mentioned earlier in the thread, is a lot of people do not like to use them or simply WON'T use them. I think there are a number of factors for this attitude, but one of the biggest is that a wiki can store a huge amount of information, but does not typically provide a simple and intuitive way to retrieve and view the data. Category pages are overwhelming, especially to new users, if they have dozens and dozens of links on them. To make it more complicated, the links are just vanilla titles with no real description which can be very unhelpful in certain circumstances where you may not know exactly what you need to look at (new users, again).
Another example of how unhelpful a wiki can be is when you use the search function. When you search for something you expect to get at least a couple of results. With the xbmc wiki, you tend to get nothing at all with more generic queries--at first. If you are very specific and your query has a a dedicated page of the same name (i.e. advancedsettings.xml) you are taken directly to the page. However, search for something more vague such as "MySQL errors" and you get nada:
On that page if you click the Check "All" button and search again, you will get several results. That is good, however a lot of people won't intuit that and will be frustrated that a "basic" query seems to lead to zero results most of the time.
Admittedly, using the check all option will produce results that may be rather generic, however it demonstrates that the search feature DOES work. When you keep getting blank results, it only takes 2 or 3 of those before you start wondering if the search function actually works at all. If you are new to wiki's in particular, or not very internet/technically savy, you are going to give up on that first page and run to the forum instead. Users, in general, do not want to spend hours reading through a bunch of stuff that explains every little detail that may or may not be directly related to their problem. They want answers and they want them now. That means they have to manage a search that produces results that QUICKLY leads them to their solution, OR they are going to post on the forum and wait for someone to spell it out for them. The people that like getting under the hood and digging through things really are a minority group.
Personally, I use Google's site search function for just about any searches I make on any website. I am very comfortable with Google search, I know what to expect from Google, and it's dang hard to beat a search engine that has spent billions of dollars on updating and maintaining it's search features. For example, using the same MySQL errors query with Google site search:
Google wiki search.
In this case, I am using a very generic query which also does not have a lot of information spread throughout the wiki, so I only get 14 results (google hides 3). The wiki search only produced 8 results with the same query. I prefer to have as many results as possible returned, regardless of how vague they may be, if I am searching for something that is poorly documented-- but that's just me.
Regardless of the search engine you use, coming up with zero results on a regular basis WILL deter users from actually using the wiki, so anything you can do to prevent that would probably be beneficial to your end goal here. Over the years, especially on forums, I have come to realize that many (perhaps most?) people are simply not good at crafting GOOD search queries, which naturally leads to people asking the same questions over and over again. Some people don't even bother with a search, but I don't have a good solution for that except a 3' long 2x4 to the back of the head.
I'm not suggesting that catering to lazy users is necessarily the "right" or "best" way to approach things, but I AM suggesting that if you want the wiki to be more widely adopted and you want to stop seeing the same questions in the forums as often, you WILL have to make things as easy as humanly possible because people are just fricken lazy--and often stupid (XBMC doesn't have any stupid users though. I'm just saying "users" in general...)
If the thing you are interested in learning about is not directly mentioned and linked on the main page, and you try using the search and get no results, how does an "average user" find what they are looking for? I believe the answer to that is they either give up, come to the forum instead, or try their luck with a WWW search on Google (or whatever search engine they favor). In that case, if there WAS a page with a lot of good info on the subject they were looking for, they will have missed it (unless someone points them to the page) and the wiki has not done it's job.
My next comment relates to outdated information. The very nature of a wiki makes it impossible to keep everything updated, and the deprecated information from being confused with the current versions. For instance, if someone had been using material that referenced the keymaps.xml discussed earlier in the thread on their pre-eden build, they would run into problems and not understand why (again leading to a possible repeat question in the forum). In a case such as this, it would be ideal to have a very obvious button or link for anyone to click on to flag the page as outdated, which would then alert someone on the wiki staff so they could verify this and either alert users that the information is no longer relevant/accurate and is flagged for update when someone gets to it or move it to an "archive" and replace it with a generic placeholder and request for current version specific information from the community--along with a link to the old information so people at least have a place to START until new information is added for the current version.
Obviously, it's probably best to keep the old data around for people that are still running old versions for whatever reason. However, the mix of old and new information is VERY confusing for many users, and could potentially lead to major mistakes being made with their installs. It would be ideal if these pages could not only be updated for current builds, but also "archive" the older information to help avoid confusion AND provide some form of legacy support. The "archived" pages should be identified by xbmc specific builds, and should be very obviously different from current build information pages. Perhaps a color coded banner of some sort at the top of each page with the build name included. Then you could have a link to the "archived" wiki on the main page (for easy legacy support) which would eventually be a mirror of the current wiki but only containing information for legacy versions as well as provide the legacy users a clear and easy way to find what they need without adding as much confusion for the current version users.
Lastly, wiki pages that contain instructions for multiple operating systems on the same page CAN be confusing if they are not very carefully formatted. Often times these types of pages will have the first few steps outlined as universal steps. Then in the middle, things will start branching off for different OS'es. At this point, it can quickly get overly complicated to follow these instructions, especially if the instructions branch by OS, then merge back to a universal format, then branch again, and so on. The simple solution for this is to try and implement a template for instructions that uses something like a simple color coded border around code boxes for each OS. If each OS consistently uses the same color coded boxes for OS specific steps, then users can quickly identify the steps that apply to them and ignore the rest without confusion. No color code means it is a step that you need to follow, regardless of OS.
Of course, the biggest hurdles for the last 2 issues I raised are implementing the features with wiki editors adhering to the systems, and of course the huge task of modifying the content already in place. I'm not saying all of this is 100% perfect or that I have all the answers, these are just observations that I thought might be productive to the overall user satisfaction of the wiki. Implementing an archive feature alone would be a massive project, so I realize it is highly unlikely. Regardless, all of the work that has been done on the wiki is a great service to this community and I am sure everyone appreciates the effort.
Apologies for writing such a long diatribe. I have tried consolidating my thoughts some, but I guess I am too tired to articulate my thoughts with fewer words tonight
- Chris! - 2011-12-30
That is a comprehensive statement. I think my over riding thoughts on the matter hinge on two things:
- No-one is paid to do this so wiki time is obviously limited
- There will always be users that ask on forums before they look in the wiki (no matter how well formattedit is) - a blunt forum reply could be used
That said the points you raise are valid.
- Ned Scott - 2011-12-31
This is a great write up/summary, j114. I think I agree with 95% of what you're saying. We have a lot of ideas on how to improve a lot of this stuff, and I think everyone will like the end result.
There's going to be more guidelines for people who want to contribute to make clear that things like a "how-to" needs to be plainly spelled out. Like you said, you can't write instructions or help guides assuming the reader knows one thing or another. We're also looking at using some of the great "beginners guides" that users have made on the forums to either replace or augment our own Quick Start Guide.
There's also a lot of pages that make the mistake of mixing advanced content with basic content. For example, we'll have a write up on how to access one feature through the GUI, but on the same page explain how the xml files are formatted. When a new user sees that they feel overwhelmed and turned off. I'm hoping to provide more separation between "the basics" and the "meaty details" pages. Like there will probably be just a basic page for a given topic for starters, and it will have "for more detailed information on this topic, click here", as an example.
We totally plan on replacing the default search engine in our copy of MediaWiki. People who've used MediaWiki (on Wikipedia or other sites) know how much it just sucks. I can certainly attest to that. Thankfully there are some more powerful replacements that we can try in the form of a MediaWiki extension, but it just hasn't been set up yet. Even other Team-XBMC developers have requested this, since we use the wiki for a lot of the technical documentation as well.
However, from your screen shot it should be searching more than "category" by default. I might have set something wrong when I last ran the default settings. I'll be sure to check that out so that searches for everyone will include all the "content" namespaces by default (the main space, HOW-TO, Add-on, etc).
Category pages are still going to be there (for various technical reasons, and some are okay for browsing), but we'll eventually stop directing people straight to them. A combination of sub-topic "navigation templates" and dynamic summary pages will be used instead. One idea I've had that should work out really well is that each page will be able to have "summary meta-data" on that page (so you don't have to remember to edit each list page). Then that summary will be displayed on a dynamically generated list (basically resulting in categories + summaries). When it's all said and done it should be pretty intuitive, and will probably help with search results as well.
Outdated pages are going to get some better/more descriptive tags on them (right now we only have "incomplete", "cleanup", and "outdated"). By the time Eden comes out I want to be able to have every "Online Manual" page be tagged like "this page has been updated for XBMC v11 (Eden)" or "this page has not been checked for updates" or some description like that, so that it's very clear when a page has been updated for a major release.
I don't think it's the very nature of a wiki makes it hard to be updated. Wikis are very flexible and can be used in so many different ways. It depends largely on how the wiki is set up. While the original contributors to the wiki have done some great work, the wiki wasn't really set up that great when it was started. I'm looking at ways to reduce redundant work (like being able to transclude information from one page to another, so it only has to be updated once instead of twice), being able to flag/tag outdated/incorrect information, and guidelines for people who contribute so they know how things should look and where they should go (as well as making it easy to find where we need help). There's even a lot of redundant pages that hopefully will be cleaned up or merged. (I think there's at least three different pages that talk about adding/scanning videos to the library, for example)
The wiki for a long time (a year or two, I think, maybe longer) was locked down because of massive spam problems. This meant no new people to help update things, and very few people actively editing anything. We've since installed spam blacklists and spambot IP checkers that has drastically improved this to the point where editing is now open once again. No longer do people have to request on the forums for access. Instead they can just register an account and start editing right away.
People are slowly starting to come back and get comfortable with contributing again, and I have some incentives planned to lure even more people in (like everyone who registers can have their own pages dedicated to their own personal set-ups, with pictures and parts lists and more). We also plan on inviting add-on developers to use our new bot-generated add-on pages as a way to both handle development documentation and to be able to list info for end users like "known issues" or "where to report problems for this add-on". (again, finding a way to have that information connected, but somewhat separate, as to not overwhelm users).
We have some great features and tools (some already installed and usable) in store for the Wiki, like embedded youtube video tutorials, and linking to the forums for page discussion instead of the confusing wiki talk page system.
Regarding old data, right now to just make things easier I've been going at pages (and telling others to do the same) that everything on the wiki from now on out should apply for XBMC v11 (Eden). I try to avoid deletinging pages (even "deleted" content is still saved in the database, but just not accessible to normal users), and instead pages are either updated or redirected, so old information can be found (every version of a page is saved, after all). Even our old xbox pages are still there, but just blanked with a message directing people to the xbmc4xbox wiki, which has a copy of those pages. When people request that a certain page/topic be restored (such as info on the old HTTP API) I do so, but place it in a new "Archive:" namespace that by default keeps it out of normal wiki searches.
I've been thinking of ways people could read a how-to page and then come across an OS specific step that only shows what they need. I'd like to come up with something that would perhaps box up that section and allow a user to "tab" to their OS. That way the reader only sees the instructions that apply to them. There's a few ways to do that, it's just a matter of getting to it and setting something up. It should be pretty slick once implemented, though.
One idea I had (for the far future, given how much there is to do) is let people do the same thing for skins. As in take a generic How-to page and let someone select what XBMC Skin they use, and have the page and screen shots reflect that dynamically. Depending on the skin, this should be do-able and easy for both the reader and the person making the how-to. This will likely be only for basic topics, too, since skins can greatly vary in features.
I'm not sure if I replied to all of your comments, but be assured that I'm reading the whole thing and even getting some additional ideas based on your suggestions. You've written a great page of feedback and ideas that really helps me organize my thoughts (as many of the ones I've just mention I sometimes forget to write down, and then I forget about them for a while) and have given me several new ideas. This is the kind of feedback that will help us out greatly, and if you think of anything else, don't hesitate to post about it. Thank you so much for taking the time to write all of that, and I hope I've been able to shed some light on what the future might look like (if all goes well) for our community wiki.
- j114 - 2012-01-01
Pseudo7, I completely agree with both of your points. My point was only to demonstrate some keys areas that needed some framework tweaks (search) and collaborative tweaks (instructional templates, for example) to make the entire wiki more streamlined and unified. As you say though, time is limited and that really is the overriding factor of any significant changes that can be made to a project of this scale.
Ned, that all sounds really, really, good. I didn't have any ground breaking suggestions there and I assumed most of it was at least considered at some point or another, but I thought it might be helpful for everyone to have kind of a documented list of things that are problematic in a general sense.
It's ironic that you mentioned the add-on devs being included because that is one of the things that I had intended to mention and it slipped through the cracks between when I started writing that and finished writing it. I think it would be extremely helpful for the wiki, the add-on devs, AND the community if these add-ons (particularly skins and add-ons from the default repository) had their own pages that essentially contained all of the info the devs typically put in the first post (or first few posts) in their forum threads. Rather than continuing to do that, they can instead simply have a support thread (linked from the wiki page, as you mentioned). The added bonus is that it will drive more wiki traffic, introduce more users to the wiki, and make people more comfortable with the wiki as a source of first line support. Over time, users will learn to just check the wiki for new add-ons or updates on existing add-ons. I, for one, would much prefer a consolidated list of add-ons to browsing through the add-ons forum.
One thing that I see a LOT of in this community is people that are not that technical or lacking any kind of coding skills making comments like "If there is any kind of help that I can offer with my limited skills...." to many of the add-on devs. Well, THIS is exactly the kind of thing that those types of users can help with. Your idea for skin-specific instructions, for example, is something that any moderately capable XBMC user can help out with which helps XBMC but also helps the specific skin designers avoid many common support issues.
Once instructions have been set up with the Confluence skin (or whatever the default skin may be at the time), a simple request to other skin users to duplicate these instructions with their skin of choice could make this a very easy goal to accomplish. I'd be willing to bet that there is at least one user of each skin at any given time that would be willing to blow 20 minutes of their time adjusting the confluence instructions to their preferred skin if they know that this is a goal you are trying to reach.
Really, I think all of your ideas are great ones and some day it will lead to a fantastic wiki. The only "problem" with any of the ideas (yours, mine, anyone's) is it takes a heck of a lot less time to come up with ideas than it does to implement them. The idea of a a good set of guidelines for the community on how to contribute to the wiki is a great idea. It opens up the door for those that want to contribute without any need for strong technical expertise, and greatly reduces the workload. It's a lot easier to edit a wiki page written (in English) by someone that has maybe speaks another language, primarily, or poor grammar/spelling than it is to write one from the ground up--so even "lazy" contributors have a way to contribute in a very positive and beneficial way.
Obviously the key to significant change on a large scale in a faster time frame is to engage and employ the community. I think you are doing a lot to try and make that happen, and the more user friendly the wiki is to use for support, the more it will entice users to contribute to the wiki-- just as they do the forums.
And I am bordering on ranting again. I should probably stop posting right before bed.
- HenryFord - 2012-01-25
I don't know wether this is the right place to ask this question, but I didn't want to open up a new thread for this:
Is MediaWiki the best decision for a Wiki heavily focused on documentation?
I asked myself this question more and more in the last two weeks - i for one think that the mediaWiki is probably just not the right kind of wiki to use in this regard. I came to test out (and installing, setting up, etc., etc.) the DokuWiki in the last two weeks (coincident? I don't think so ) and to what I can gather so far it is WAY better at documenting things in a nice, neat structure than mediaWiki ist - and isn't that all the XBMC-Wiki should be about? Documentation? Maybe it would be a good idea to transfer the mediawiki to a dokuwiki-setup in order to give users a more intuitive access to the documentation they are seeking. Especially the search-function in mediawiki is so messed up, you hardly find what you were looking for in the first place. I could be of help here - helping in transfering the current wiki to a new envoirenment. Of course it would take time - but that is time I am more than willing to invest in this project.
I surely don't know the exact interna over at Team-XBMC, but maybe it would make sense to appoint someone solely to the Wiki (if that is not already the case, that is)?