Hybrid forum/wiki FAQ stuff for ATV2/iOS
#16
I think what Buadhai is trying to get at, Ned (and I agree with him on this point, as a professional writer and editor who also did a couple of decades worth of in-home PC tech support), is that although it is technically correct that you visit "Cydia" to install via the command line, in practice that is irrelevant to the end-user. An end-user just wants to know how to install XBMC. They don't need to know that it's a "Cydia" version, and don't need to know anything about Cydia. In fact, as Buadhai pointed out, the mere mention of Cydia is confusing.

You said, "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." Actually, I think that's exactly what a FAQ and how-to are supposed to do--get someone from point A to point B. If they want to learn more about something BEYOND how to get from point A to point B, then by all means have additional resources available. But the primary goal of a FAQ and how-to should be to give an uneducated user the minimum information they need--and no more than that--to get a task done.

An instruction manual should not be about "teaching." It should be about giving people the information they need to get something done. Additional information for people who want to learn the in-depth information about the subject can be linked to separately.

That's why, for instance, in the "How To Install XBMC" section, I wouldn't mention Cydia at all; I'd just give them the step-by-step bare minimum info. Then I'd put something like, "for additional detailed information about the installation process, see these wiki links:....", and have THOSE links explain the details of Cydia, the process, etc etc.

Anyway, that's just my opinion, for whatever it's worth Smile
- Amazon FireTV Stick 4K running latest stable Kodi version
- Sony Bravia XBR-x900h Android TV running latest stable Kodi version
- Skin: Aeon Nox: SiLVO
Reply
#17
rant/

Have people gotten so lazy that they can't look up a word using google ? That's the first thing I hit when I run across some word or phrase I don't understand. It's the new black in dictionaries.

There is a certain level of effort needed to install and run XBMC on iOS/ATV2 devices, it's not a one click and you are done. In order to do this, you must be willing to learn some new things and blindly copy/pasting command-line commands is a sure fire way to get frustrated and confused. I see this time and time again in the forums.

/rant
Reply
#18
davilla Wrote:rant/

Have people gotten so lazy that they can't look up a word using google ? That's the first thing I hit when I run across some word or phrase I don't understand. It's the new black in dictionaries.
With all due respect (and with a great deal of gratitude for the hard work that you personally, and the rest of the XBMC team, do), I'm not sure I understand this attitude. Surely the aim is to make the wiki/docs clear enough and simple enough that people won't have to resort to Google?

If you're indirectly asking "why don't people use Google more," my answer is "you're right, some people are indeed too lazy to use it, or don't know quite how to use it well." But, does the fact that there are lazy people out there who don't use Google mean that the docs shouldn't be made simpler for everyone?

davilla Wrote:There is a certain level of effort needed to install and run XBMC on iOS/ATV2 devices, it's not a one click and you are done. In order to do this, you must be willing to learn some new things and blindly copy/pasting command-line commands is a sure fire way to get frustrated and confused. I see this time and time again in the forums.
/rant
I absolutely agree that XBMC on iOS/ATV2 is not exactly the type of technology that lends itself easily to the "Best Buy" crowd (you know the type of person I'm talking about...who just wants their "gadget" to work and has no interest in learning how it does so). But unfortunately, as I think I mentioned once before, you guys are to some extent victims of your own success. You've done such a good job of coding XBMC for iOS that it's becoming more accessible to less technically-minded people, as opposed to being exclusively the domain of technophiles who eat Linux for breakfast and can dissect Assembly language. I urge you to consider what that means in terms of how the docs need to be written (or re-written as the case may be).

Blindly copying/pasting command line commands works fine, as long as the instructions and terminology are extremely clear and simple, and are aimed at these less-technical users. I'm guessing the less-technical users are the ones who usually get frustrated and confused in the forum...am I right? If so, doesn't that imply that perhaps the instructions need to be simplified, rather than made even more complicated and "instructional"?

Again, there's nothing wrong with providing "copy and paste" simple, clear commands that say exactly what those commands will do ("to install, copy A, B, and C into Terminal, hit Enter after each."). Having those simple copy/paste commands doesn't mean that extreme detail can't be provided separately somewhere else where anyone can access.
- Amazon FireTV Stick 4K running latest stable Kodi version
- Sony Bravia XBR-x900h Android TV running latest stable Kodi version
- Skin: Aeon Nox: SiLVO
Reply
#19
canadave Wrote:I absolutely agree that XBMC on iOS/ATV2 is not exactly the type of technology that lends itself easily to the "Best Buy" crowd (you know the type of person I'm talking about...who just wants their "gadget" to work and has no interest in learning how it does so). But unfortunately, as I think I mentioned once before, you guys are to some extent victims of your own success. You've done such a good job of coding XBMC for iOS that it's becoming more accessible to less technically-minded people, as opposed to being exclusively the domain of technophiles who eat Linux for breakfast and can dissect Assembly language. I urge you to consider what that means in terms of how the docs need to be written (or re-written as the case may be).

Just wanted to add...remember too that some people turn to XBMC not because they want to learn about it, or are up for a challenge; rather, some people turn to XBMC because they are desperate for a good media playing solution that interacts with their PC, even if they're non-technical people. Maybe they're just media literate enough to download movies from torrent sites (several of my friends' wives are juuust literate enough to do this, but have never used a Terminal window before). They've looked at things like Boxee Box, Popcorn Hour, etc....and then there's this cool software that works with Apple TV's (and we all know how many non-technical consumers love Apple)! All they know is that they have some movies on their computers that they want to be able to play on their TV. How's that for non-technical? Smile

So then you get this non-techie consumer who does a little Google surfing and finds out that there's this XBMC that you can use on an Apple TV to play their files from their computer. Figuring they'll just plunge in, they buy the Apple TV, start reading about XBMC, and promptly get confused. These are the types of people who just need simple, basic instructions and are not going to be literate enough, nor interested enough, in learning anything further.

So the question then becomes: what is the attitude toward these people going to be? Is it going to be "sorry, we can't cater to you, go learn more and then come back when you're ready?" Is it going to be "here's your instructions...they're going to go into great detail, and you will likely not understand it, or will need to Google the terms that we use in it"? Or is it going to be "XBMC can be complicated, be warned; but here are the simple instructions you need to get it installed. We urge you to read more HERE [link] and understand what you're doing, or else you are likely to run into problems"?

Those would seem to be the three main options; of the three, I think the last makes the most sense.
- Amazon FireTV Stick 4K running latest stable Kodi version
- Sony Bravia XBR-x900h Android TV running latest stable Kodi version
- Skin: Aeon Nox: SiLVO
Reply
#20
Well - on the one side i understand what davilla wants to say. I think its an "issue" of us developers which most of us have in common.

Its the "We have a fuckin hard time to code and build all this stuff struggling with murphy all the time - its unfair if the user has only to click one button for using it" - thing. I know its hard to understand and sounds unfair to the user too. Its a kind of payback to such kind of (annoying) users which state something like "Can't be that hard to implement feature xyz - go go go" - ergo - "can't be that hard to google something for getting xbmc to run" Big Grin

But on an objective view - its best to give a good documentation to the users (and with users i mean users from all kind of knowledge). And i bet if this would be accomplished the users would appreciate.

For example i've bought a product where i wasn't much into - and the producing devs made up a manual which is the best manual i've ever had. Its the only product i know of which had such a great and short and easy understandable manual. This is something which most of the other users of that product mentioned in the producers forum too.

What i want to say - a good manual is something the user remembers and appreciates - not only the product (XBMC) itself.
AppleTV4/iPhone/iPod/iPad: HowTo find debug logs and everything else which the devs like so much: click here
HowTo setup NFS for Kodi: NFS (wiki)
HowTo configure avahi (zeroconf): Avahi_Zeroconf (wiki)
READ THE IOS FAQ!: iOS FAQ (wiki)
Reply
#21
Even as it is worded now you never have to know or look up what Cydia means. It's a NAME. Before we just called it "repo copy" and that's even more confusing. It's an arbitrary name to call the .deb/repo/cydia/"stable" (it's not stable) version. It says "To install from Cydia do this" and that's the end of it. The word Cydia is now linked to a wikipedia article if they want to know what it is.

Every single jailbreaker with a touchscreen device knows what Cydia is because that's the only way you install applications on a jailbroken iOS device. I understand that there's a lot of ATV2 users who will never go past just owning the ATV2, but they are in the minority of iOS users.

How many times have we said "SSH" or "SFTP" on the forums or on the wiki with out ever explaining exactly what those are? We don't have to, because they're just names. We could even explain things without calling them that, but there's the potential that it will cause confusion later. Same deal here. ATV2 jailbreaking is only growing and it will only be a matter of time before Cydia itself has a GUI installer on it. All NitoTV does is run some terminal commands.

The fact that some of you don't know what Cydia is actually making you think this is a bigger issue than it is. It's a name, a label, to help distinguish between the nightlies and the packaged repo. Of all the words to call that section "repo, "stable", chocolate covered hot dog, NitoTV install" Cydia was no more or less confusing than the others, and was a lot more accurate. So I ask you guys: where's the fire?

Don't let a new word scare you. You never have to know what it means. A set of blow-by-blow install instructions will walk the user through everything.

Also, this is a quickly evolving unstable program that isn't even in beta yet being used on a modified product that has been a new experience for both users and developers alike. It's not that hard to get XBMC to work, but this isn't for the faint hearted. People are testing experimental software and are expected to be able to give things like debug logs and crash reports. The actual release of Eden (v11) will no doubt be a select and click install on the ATV2 in the future, but we're still in the testing phase.

This is the install page we are talking about. Presumably the FAQ (what this thread was started for) would explain what Cydia is.


Does anyone actually have any input on the merging of the forum FAQ and the wiki FAQ?
Reply
#22
The skilled writer of documentation knows that the task is to write for the user who is really out there, not for the user the writer wishes was out there.
Reply
#23
canadave made some good points about the level at which answers to FAQs should be pitched. It's certainly what we should be aiming for rather than any in depth explanation. But looking at the current FAQ I think this is what we're already doing - it's certainly the way I try and write an FAQ entry when I do one, and given the way the FAQs look, I'd say that it's what everybody else does too. Of course if anybody thinks that an FAQ entry is too complicated then we're all happy to take suggestions on how it can be made clearer. With the wiki anybody can directly edit the question and answer to make it clearer.

As for use of the word Cydia: I agree with Ned. It's a name. Knowing what that name means is immaterial. Of course, putting a link to the wikipedia entry will satisfy some peoples' curiosity, so it is worth having, but ultimately its not important. What I would say about the Installation page on the wiki is that it might be worth spelling out what the difference between the two builds are so that a new user knows why there are two there to choose from. I've had a go at writing a short introduction. I was going to add it to the wiki, but to enter it under a new heading I think that I might need to get the relevant permission - I'll get Ned to sort that out for me and then add it to the wiki.

*EDIT* changes have now been made to the wiki, and are open to removal/changes if you feel they are necessary. [link]
Reply
#24
As for the FAQ direct questions:

Ned Scott Wrote: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.
Good idea to have a bit more info for those who want it, but I'd definitely go with an external link if you can find one

Quote:•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?
imo, the best thing to do with these general queries would probably be to direct to another part of the wiki. I've not checked the QSG as it stands, but if it doesn't actually give the answers then, as a temporary measure, until that's fixed then you're probably right to go with the iOS specific versions. Where possible though, do link to somewhere else on the wiki

Quote:•Mention that custom keymap for the apple remote? How about link to a new on-wiki copy!
sounds good!

Quote: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.
agreed. I'm leaning towards a new page for problem specifi FAQ, but I'm not certain about that because of the possibility of people not finding the question they're looking for (as I mentioned in my last post re: basic and advanced questions)

Quote:•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
Honestly, I don't think that it'd be a great loss to drop this question entirely. I don't think that it's a freqently asked question. I've been using XBMC for about 4 years, and the first time I'd heard of XBMS was when I saw it in the FAQ (it wasn't me who added it, obviously Big Grin)

Quote:•"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.
yep

Quote:Some things that neither FAQ seems to have: <snip>
Just add them. They are frequently asked questions after all! Can't help you with the audio one though. I'm not familiar with it either.


And just a very quick note on layout: it'd probably be good to stick a couple of line breaks before each new section header (e.g. "Touch screen iOS devices"). They tend to get a bit lost in all the other text otherwise.
Reply
#25
Ned Scott Wrote:*facepalms*

Does anyone actually have any input on the merging of the forum FAQ and the wiki FAQ?

Re: merge feedback, I think step 1 you have pretty much under control, i.e. combine the 2 into 1 wiki page... removing anything that clearly doesn't need to be there.

One of the most important things I think, for documentation, is that there's one official source for the information... that'll be the wiki FAQ.

The conciseness of the content is almost as important. If the content tries to explain every word that any user hadn't heard of before the doc would be huge and never read. It should be made as simple as possible but no simpler. Does the end user need to know what Cydia means to use XBMC on ATV2, no, so it doesn't need to be in there. The hyperlink is a nice courtesy to the end user that doesn't hurt the readability of the FAQ.

Jailbreaking is off the beaten path. Once you go down that path there's no expectation of perfection/spoon feeding but there is an expectation of personal responsibility... to read faqs, to search before posting, to use Google, to accept that the software and support is a favor being done for you. Bugs and instability need to be expected and complaining minimized. Google is the solution to fill in your own blanks that aren't on the critical path, e.g. you don't need to know what Cydia means to jailbreak and install/use XBMC. Anything not on the critical path is the responsibility of the end user and shouldn't be allowed to degrade the usefulness of the documentation to the broader audience.
Reply
#26
Sorry for going a little nutty on the Cydia part, guys. I still think it should be there and won't be significant instruction-creep, but whatever. It's not that I feel strongly about it, but rather, it takes me a lot of words to express my ideas/impression on things sometimes. I hope I didn't scare anyone else off who might be reading this thread from helping out on the wiki ;)

And thank you to everyone who's been helping so far! Things are looking great.

If anyone is new to editing a wiki a great place to start learning (though it's not hard! It's just text with some basic markup) is Wikipedia's editing tutorial: http://en.wikipedia.org/wiki/Wikipedia:Tutorial
Reply
#27
wiki.xbmc.org/index.php?title=XBMC_for_iOS_specific_FAQ

I think it's about 90% done.

Notes:
I haven't put in anything for downgrading, though I think that probably should just be covered in the install guides.

Haven't put anything in yet for "Why not in App Store" because I wanted to have something fairly neutral and calm. No flying off the handle about big companies and speculation about the GPL.

Needs better guides/links for setting up basic network shares. I really had a brain fart on that and didn't have anything bookmarked myself. The wiki is surprisingly lacking in any good page to describe how to add network shares.

I'm not sure if all the touch controls for iDevices are listed

It's kind of a pain in the butt to edit right now because of the alternating color thing. It's pretty easy to figure out how it's done, but whenever you add/remove/reorder something then you have to reorder the colors. At the same time I think it really helps the sub-sections feel more separated and clear. I'll probably whip up a wiki template that will automatically select alternating colors (once I remember how I did it before..).

Feel free to work on any of the things I've noted here, or anything you've noted, or just feel like should be added/changed/whatever. It is a wiki after all.

Also, all the forum posts we link to (and many more) would probably make for great how-to entries on the wiki. If anyone has any in mind be sure to mention it or add it yourself. New accounts can't make new pages until they've made five edits and are at least two days old, but if you message me I can manually grant you access so you don't have to wait.
Reply
#28
- Alternating colors will likely prevent a few people from doing any editing until it's resolved. Looking forward to seeing how to do templates /w alternating colors Smile The alternating colors are different than the other XBMC FAQs but I think it works.

- Another diff is the TOC limit doesn't let you see the questions at a glance. To find something you have to use the browser's find command or manually scroll through the questions. Ya the TOC would get really long if all the questions were in it but I think it's probably a better way to go.

- The nice thing about the TOC is if it contains the questions that makes it really easy to link directly to a question from a thread in the forums. I assume there's other ways to create those links (anchors, etc) but they seem to take extra steps... anyone know an easier way?
Reply
#29
I made a couple of changes/additions the other day. Then, I went back and looked today and was dismayed. Please do away with the alternating colors. IMO, it is unnecessary and distracting.

Just my two cents.
Reply
#30
Good work in tidying this section up.

I recently purchased an ATV2 purely for running XBMC and probably spent the best past of three full nights reading old and new forum posts, wiki pages and blog entries (outside of xbmc.org) to try and understand what was required. Once I got my head round it all it was relatively easy to jailbreak and install XBMC. Thread 99315 was most useful..

Ta,
Chris
Reply

Logout Mark Read Team Forum Stats Members Help
Hybrid forum/wiki FAQ stuff for ATV2/iOS0