2011-12-31, 12:03
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.
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.
