Hybrid forum/wiki FAQ stuff for ATV2/iOS

  Thread Rating:
  • 0 Votes - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Post Reply
Ned Scott Offline
Team-Kodi Wiki Guy
Posts: 22,464
Joined: Jan 2011
Reputation: 296
Location: Arizona, USA
Post: #1
For those of you who don't know I've been recently working on the XBMC Wiki and trying to bring it up to shape. There's been lots of really old pages, spam, technical issues, and so on. It's been in such a mess that we tend to just ignore it and use the forums more often for the cutting edge info.

However, for the iOS forum we've gotten to a weird point where we now have two FAQs. One on the forums and one on the wiki. The one on the forums is actually much easier to read, in big part to procrastinator writing such a good FAQ. It's also not such a huge WALL-OF-TEXT as the one on the wiki. At the same time the wiki FAQ might have some stuff the forum wiki doesn't since anyone can edit it. Having two FAQs is also very confusing to newcomers, who are supposed to benefit the most from an FAQ.

And so.. I think we should look at merging the two FAQs. Take the good, throw out the bad, and maybe make some brand new improvements.

One of the things we are able to do on the wiki is spread ourselves out. We can make a very basic FAQ at first rather than a huge wall of text, and then dive deeper. Or we can just categorize the FAQ completely like how it's done on the forum. Or both. There are a ton of formatting options available (show/hide sections, multiple pages, jump to sections), and anyone can edit it at the same time (which could lead to chaos, but hopefully not. Most small wiki's like ours tend to be very stable and people tend to work together better).

So basically this is a brainstorm thread. How should we merge the two FAQs? What questions are we not answering? What questions are we answering but not needing to? Should we tier and/or categorize questions/answers? Should we include pictures of kittens doing cute things?

I find the best way to think about it is to just pretend you are a brand new user and put yourself through the steps. Look at either FAQ and ask yourself how well does it do, or what could have been changed to make a new user more informed or less confused. Also don't just note the negative, but note the positive! Find where the FAQs shine so we can apply that even more.

If anyone wants access on the wiki (anyone with an account can edit, but new pages can only be made with access granted) to make their own draft page to play with let me know. Just PM me with your wiki username (make one if you haven't already).

Alternatively, if you just want to make a mock up in a PDF or even a table napkin, throw a link to that as well. It's pretty easy to adapt formatting for a wiki, so if you want to try some ideas out in a program you are more familiar with then go for it.

And of course don't forget to also just throw ideas out in this thread as well. Feed off of each other's ideas and such. When one example shows up don't be afraid to make your own implementation of their example.

At the same time don't let it overwhelm you. An FAQ doesn't have to answer every possible question or be perfect. Nor do you have to create an example if you just want to throw out some ideas. If anything it's the formatting and organization that needs the most attention right now, but any and all ideas are welcome.

EDIT: Here's a link to all our ATV2 related wiki pages, including the FAQ. Feel free to dive right and and even test ideas out as we discuss them. It's a wiki after all and any mistakes are easily undone by the click of a button, so don't be afraid. Feel free to dive into any of the pages if you have an idea or see something you can improve. On Wikipedia they have a phrase that works well here: Be Bold!

wiki.xbmc.org/index.php?title=Category:IOS
wiki.xbmc.org/index.php?title=XBMC_for_iOS_specific_FAQ
(This post was last modified: 2011-09-13 02:53 by Ned Scott.)
find quote
canadave Offline
Fan
Posts: 730
Joined: Jul 2011
Reputation: 16
Location: Nova Scotia, Canada
Post: #2
I like the kittens idea. It'll make people sit up and take notice Wink

Seriously, this is a great idea. I mentioned this in a PM separately, but my vote would be to make an "Installation/FAQ/Known Issues - READ HERE FIRST!!" thread (with that exact title), and make it an Announcement rather than simply a Sticky.

In that thread, I would simply have a link to the wiki, explain how everything can be found at the wiki, and provide links to some popular or helpful pages on the wiki (the installation page, the FAQ page, some popular config pages, etc), and then "please don't ask any questions in the forum until you've searched through the wiki." Then finally some text saying "if you can't find the answer to your question in the wiki or via the links above, feel free to post a question. But please make sure to post the debug log; otherwise we won't be able to help. Here's how you can find it and post it:" and then put a link explaining it. Something to that effect.

Then, that puts the ball squarely in the wiki's court. As for what to put in there....I'll have a closer look when I get some time (hopefully later tonight) and post some ideas subsequently in this thread.

- rooted Amazon FireTV running XBMC Gotham 13.2
- 2011 Macbook Pro, running OSX Yosemite
- Skin: Aeon Nox 5
- Connecting to MySQL database on Synology DS411+ NAS via NFS.
(This post was last modified: 2011-09-07 19:11 by canadave.)
find quote
canadave Offline
Fan
Posts: 730
Joined: Jul 2011
Reputation: 16
Location: Nova Scotia, Canada
Post: #3
One other general point I wanted to make, by the way:

The thing about XBMC is that it attracts a wide disparity of types of people. There are people who come to XBMC and just want something to play their videos and music files. That's it. They're not computer experts, not versed in UNIX, they just want an alternative to Boxee Box and so on. Yet there are other people who are quite technical, are comfortable tinkering with endless tweaks and settings, etc.

To be effective, I think the instructions for XBMC (in the form of the wiki/forum FAQ) have to be simple, obvious, and easy to understand up front, yet also provide the capacity for people who want more in-depth information to be able to go find it. That's going to be a tricky tightwire act.

- rooted Amazon FireTV running XBMC Gotham 13.2
- 2011 Macbook Pro, running OSX Yosemite
- Skin: Aeon Nox 5
- Connecting to MySQL database on Synology DS411+ NAS via NFS.
find quote
procrastinator Offline
Fan
Posts: 443
Joined: Aug 2008
Reputation: 4
Location: UK
Post: #4
I think that the most simple and effective way of tidying up the FAQ would be to add more sub-headings. When people go to the FAQ they've generally got a subject in mind that they want to look up. For instance they might go there and want to look something up on an installation issue they're having. If there's an "installation" sub-heading they're only going to have to look at 5 or 6 questions (example figure, not accurate) to find whether what they want to know is already there, rather than looking under a "general" heading where they'd have to look through 20-30 questions. It cuts down the wall-o-text to a manageable brick or two.

The problem with having separate pages for basic and advanced questions is that people might miss what they're looking for. For example they might think they have a basic question, and so only check the basic page, when in fact it they should've checked the advanced page (or vice versa). If all questions were to be kept on one page the basic and advanced questions could be separated simply by putting them in order under each heading; with a block of basic questions, then a block of more advanced questions, then the next topic with a repeat of the basic then advanced question structure, and so on. I'm not sure how the show/hide sections work on the wiki, but if they're in-line with the rest of the text you could hide the more advanced question block, which would keep things a bit tidier.

So those changes would look something like:
Code:
HEADING 1
----subheading 1a
--------basic questions
--------advanced questions (hidden?)
----subheading 1b
--------basic questions
--------advanced questions (hidden?)
----subheading 1c
--------basic questions
--------advanced questions (hidden?)
HEADING 2
----subheading 2a
--------basic questions
--------advanced questions (hidden?)
                   )\._.,--....,'``.      
     .b--.        /;   _.. \   _\  (`._ ,.
    `=,-,-'~~~   `----(,_..'--(,_..'`-.;.'   kitten
----subheading 2b
--------basic questions.
....etc...

As for what all the subheadings should be, I'm not entirely sure. The best time to work that out might be once you've got all the questions we want to keep laid out in front of you.

Thanks for the complement on the forum FAQ, but I should note that huge credit should also go to jd2157, who's been doing a lot of the work of keeping it up to date.
(This post was last modified: 2011-09-07 21:21 by procrastinator.)
find quote
Jeff17 Offline
Junior Member
Posts: 14
Joined: Jul 2011
Reputation: 1
Post: #5
canadave Wrote:Seriously, this is a great idea. I mentioned this in a PM separately, but my vote would be to make an "Installation/FAQ/Known Issues - READ HERE FIRST!!" thread (with that exact title), and make it an Announcement rather than simply a Sticky.

In that thread, I would simply have a link to the wiki, explain how everything can be found at the wiki, and provide links to some popular or helpful pages on the wiki (the installation page, the FAQ page, some popular config pages, etc), and then "please don't ask any questions in the forum until you've searched through the wiki." Then finally some text saying "if you can't find the answer to your question in the wiki or via the links above, feel free to post a question. But please make sure to post the debug log; otherwise we won't be able to help. Here's how you can find it and post it:" and then put a link explaining it. Something to that effect.

I vote for this approach - an announcement on the forum with links to the wiki. I think the easiest approach is to have three main ATV2 wiki pages: Installation (which the wiki already handles pretty well), Troubleshooting, and Tweaking. Then just copy and paste from the existing forum FAQ into there. After that, everyone can contribute to the wiki, so the sooner it's dumped into the wiki, the sooner everyone can start helping clean it up.

Also, is there a good reason that registered users are blocked from creating pages? Locking it down that far seems to defeat the purpose of having a wiki.

Just my two cents Big Grin
find quote
Ned Scott Offline
Team-Kodi Wiki Guy
Posts: 22,464
Joined: Jan 2011
Reputation: 296
Location: Arizona, USA
Post: #6
Jeff17 Wrote:I vote for this approach - an announcement on the forum with links to the wiki. I think the easiest approach is to have three main ATV2 wiki pages: Installation (which the wiki already handles pretty well), Troubleshooting, and Tweaking. Then just copy and paste from the existing forum FAQ into there. After that, everyone can contribute to the wiki, so the sooner it's dumped into the wiki, the sooner everyone can start helping clean it up.

Also, is there a good reason that registered users are blocked from creating pages? Locking it down that far seems to defeat the purpose of having a wiki.

Just my two cents Big Grin

They had some massive spam bot problems a while back, but looks like things will be able to be opened up again pretty soon. It should actually "auto confirm" accounts just like on Wikipedia, where you make a few edits and exist for a day or two, and then it goes "okay, if you were a bot you would have been caught by now so here's your access. And that's just the automatic settings. Once we have a better method for people to report spam it might be opened up even more/less wait time. And if anyone wants access even faster they can just contact me and I'll flip the switch early.

Actually the spam blacklist we started using has pretty much stopped all known spam for a few weeks.. It's going much better than I had hoped for.
find quote
Ned Scott Offline
Team-Kodi Wiki Guy
Posts: 22,464
Joined: Jan 2011
Reputation: 296
Location: Arizona, USA
Post: #7
Oops, seems some access settings were still messed up. If anyone tried before and wasn't able to edit, you should be able to edit now.

Also, be sure to check out the advanced editing mode with WikEd:

When logged into the wiki go to: wiki.xbmc.org/index.php?title=Special:Preferences
Then to the Gadgets tab and select "WikEd"

Gives the editing window some power tools and hopefully makes wiki editing a little easier for those who aren't that familiar with it (and if you are familiar with it you will like the additional tools it adds).
find quote
Ned Scott Offline
Team-Kodi Wiki Guy
Posts: 22,464
Joined: Jan 2011
Reputation: 296
Location: Arizona, USA
Post: #8
To update, in preparation of a merge of the two FAQs I've prettied up the Wiki FAQ a little bit to give us a better idea of what it has going for it. http://wiki.xbmc.org/index.php?title=XBM...ecific_FAQ

Some ideas I have for merging the forum FAQ. This is just making sure we are covering the the questions/topics from both FAQs (unless there's some that should be left out) rather than how we should organize it:

Work-in sections 1-2, maybe expand SSH answer with a link for "SSH 101" either on our wiki or to an external guide if one exists.

Most of Section 3's content is in the wiki FAQ except a few things (need to add forum link on Logitech Harmony post, no mention about lack of ATV2 volume control, the "outputs only 720" needs to be clearer on wiki FAQ)

Section 4 is mostly there but needs:
•"how to downgrade" for both Touch Screen and ATV2. I always hesitate to include downgrading instructions, but it literally is a question we get asked all the time.

•there's some universal basics we've been including (adding shares, mysql sharing, etc) and I'm not sure if we should keep repeating them or find a better way to link between something like the Quick Start Guide (which also needs to be updates). Probably best to just repeat iOS specific versions of those universal issues for now until the QSG and other manual pages are up to speed?

•For "why isn't XBMC on the App Store" I think we should simplify it to something like "private APIs and several unknowns" to avoid debates about if the App Store is GPL friendly/evil/whatever (Something to that extent), rather than link to the previous thread about the issue.

•Mention that custom keymap for the apple remote? How about link to a new on-wiki copy! wiki.xbmc.org/index.php?title=Keymap:Joystick.AppleRemote.xml&action=raw (remove &action=raw to edit it like a normal wiki page. Add &action=raw to make it, well, a raw xml file) And you'll notice this is in a new "Keymap:" Namespace. We can upload other versions as well (will have to use different page titles, but workable.) We can even use this for other things like advancedsettings.xml, but now I'm getting a bit off topic.

•More QSG stuff that we'll repeat for now

•Forum guides linked in the FAQ like this would make for great starting points for new how-tos in the wiki. To save time we can just keep linking them for now.

Section 5's concept of being problem-specific-FAQ is something I really like and already went head and made a similar "Basic troubleshooting" section on the Wiki version. This could easly be its own page or still share the main FAQ page.

•Add missing stuff, etc

•is the disapperance of XBMS something most will notice? Eventually it being missing in action will be covered in general on the wiki and in XBMC documentation since all pre-v11 versions no longer have XBMS

•"Is XBMC on ATV2 the same as on Windows/OSX/Linux?" I think can be dropped. We basically cover this when we keep telling people that the iOS version is in development.


Some things that neither FAQ seems to have:
•I can't install X add-on anymore/where can I find compatible versions of skins/add-ons?

•Turn off native airplay (since XBMC now includes it built in people will want to do this)

•Static sound being fixed by ATV2 16-bit setting? I'm not completely familiar with this specific issue.
find quote
Ned Scott Offline
Team-Kodi Wiki Guy
Posts: 22,464
Joined: Jan 2011
Reputation: 296
Location: Arizona, USA
Post: #9
Then of course there's how to actually lay it out. I'm thinking we can have a cross between the section devision seen on both FAQs:

A section for "here's where you go for jailbreak help/don't ask here"

A section for SSH (commands) and SSH/SFTP (file transfer)

A General "applies to both ATV2 and Touch Screen iOS" section

An ATV2 specific section

A Touch Screen specific section

Troubleshooting could be its own section, or a subsection of the ATV2 and Touch Screen sections.

Install questions/answers can all just be referred to the wiki install guide (and improved upon as needed)

Then there's more stylistic questions. Do we use colors? Do we do the Q: with A: under it like on the forum? Side by side? Or do we have the bold title with text under it like the default wiki style (the Wiki can do either easily, and even with non-headers still have linkable anchors). Include more screen shots and where? etc.

Thoughts?
(This post was last modified: 2011-09-10 22:00 by Ned Scott.)
find quote
Cranial Offline
Fan
Posts: 740
Joined: Aug 2008
Reputation: 3
Location: Sydney, Australia
Post: #10
Ned Scott Wrote:A section for SSH (commands) and SSH/SFTP (file transfer)

I think some things like this should be made locally in the wiki. It's cross platform, so it should be internally linked. It can just be a copy of an external how-to with credit given. This avoids the problem of broken links and maintains wiki layout/formatting if the xbmc wiki ever migrates.

I did a bit of work fixing up the xbmc4xbox wiki when it branched from official, and things like this were a bit of a headache.

If I have helped you in any way, please forgive me, it was entirely accidental.
find quote
Buadhai Offline
Senior Member
Posts: 258
Joined: Jul 2010
Reputation: 0
Location: Korat, Thailand
Post: #11
I'm not competent to confidently edit the wiki, but I do have some initial impressions:

- Eliminate or define jargon. For example, the "Install XBMC on ATV2" wiki starts out with "Installing the Cydia build". What's "Cydia"?

- Where people have to fill-in-the-blanks, use examples:

Code:
ssh root@<YOUR.ATV2.IP.ADDRESS>

For example:
Code:
ssh root@192.168.0.10

- Where things could go wrong, try and anticipate common errors and problems. (There's a thread here somewhere in which a guy agonizes over the installation of a nightly build. The dpkg command failed because he either didn't download the package or the download failed.)

- Try and remember what it was like before you knew everything. In other words, try to be a good teacher. That's what a wiki is all about.

Finally, thanks for all the hard work. I would never have been able to get this all working without both the wiki and the forum. All is well now - fingers crossed.
find quote
Ned Scott Offline
Team-Kodi Wiki Guy
Posts: 22,464
Joined: Jan 2011
Reputation: 296
Location: Arizona, USA
Post: #12
Buadhai Wrote:I'm not competent to confidently edit the wiki, but I do have some initial impressions:

- Eliminate or define jargon. For example, the "Install XBMC on ATV2" wiki starts out with "Installing the Cydia build". What's "Cydia"?

- Where people have to fill-in-the-blanks, use examples:

Code:
ssh root@<YOUR.ATV2.IP.ADDRESS>

For example:
Code:
ssh root@192.168.0.10

- Where things could go wrong, try and anticipate common errors and problems. (There's a thread here somewhere in which a guy agonizes over the installation of a nightly build. The dpkg command failed because he either didn't download the package or the download failed.)

- Try and remember what it was like before you knew everything. In other words, try to be a good teacher. That's what a wiki is all about.

Finally, thanks for all the hard work. I would never have been able to get this all working without both the wiki and the forum. All is well now - fingers crossed.

Thank you for the feedback! However, I must note that "Cydia" is not "jargon". It's the name of the jailbreak "app store". That's kind of like calling a program or a website "jargon" because not a lot of people have heard of it.

What we'll probably do for those kinds of things is just link to a wikipedia article on it, or our own summary.
find quote
Buadhai Offline
Senior Member
Posts: 258
Joined: Jul 2010
Reputation: 0
Location: Korat, Thailand
Post: #13
Ned Scott Wrote:Thank you for the feedback! However, I must note that "Cydia" is not "jargon". It's the name of the jailbreak "app store". That's kind of like calling a program or a website "jargon" because not a lot of people have heard of it.

This is exactly what I mean by remembering what it was like before you knew everything. I didn't know what Cydia was and had to look it up. (I started writing software in 1969, so I'm not exactly a novice when it comes to technology.) Somehow I managed to jailbreak my ATV2 without knowing what Cydia was and without ever having to visit the Cydia store or use the Cydia app. And, yes, I have an iPhone and an iPad. Never considered jailbreaking either of them.

Ned Scott Wrote:What we'll probably do for those kinds of things is just link to a wikipedia article on it, or our own summary.

That's a fine idea. But, at the moment, the wikipedia article on Cydia contains no mention of either XBMC or the Apple TV.

I still think that "Cydia" meets the definition of jargon: special words or expressions that are used by a particular profession or group and are difficult for others to understand.

IMHO "Cydia" is a special word used by the group of people who have or who have considered jailbreaking an iOS device.

But this is a trivial argument. The point is that the wiki should avoid using terms that are not generally understood, jargon or not, unless they are explained.

BTW, I've got the time and inclination to help, but perhaps not the special knowledge necessary.
find quote
Ned Scott Offline
Team-Kodi Wiki Guy
Posts: 22,464
Joined: Jan 2011
Reputation: 296
Location: Arizona, USA
Post: #14
Buadhai Wrote:This is exactly what I mean by remembering what it was like before you knew everything. I didn't know what Cydia was and had to look it up. (I started writing software in 1969, so I'm not exactly a novice when it comes to technology.) Somehow I managed to jailbreak my ATV2 without knowing what Cydia was and without ever having to visit the Cydia store or use the Cydia app. And, yes, I have an iPhone and an iPad. Never considered jailbreaking either of them.

Actually you did "visit" the Cydia store. You just used the command line interface instead of a GUI. Without Cydia you wouldn't have been able to install XBMC and the dependancies it needs. It's not jargon because it's a proper name. The whole point of a wikilink within a wiki page is that you are always one click away from learning what a word means.

I totally understand what you mean by avoiding jargon, and I agree. However, Cydia, wether it is technically considered jargon or not, is just one of those things that even the most novice of users should know about when it comes to jailbreaking.

Our FAQs and How-to's aren't just there to get someone from point A to point B, but to educate them as well. There might be a gray line on some stuff to teach or not teach, but Cydia is far from the gray line.
find quote
Buadhai Offline
Senior Member
Posts: 258
Joined: Jul 2010
Reputation: 0
Location: Korat, Thailand
Post: #15
You win. I'm done.
find quote
Post Reply