Simplify the Getting Started Page #250
Comments
mulyaj
changed the title
|
I just want to link the getting started page which will be part of the new version: https://github.com/jamulussoftware/jamuluswebsite/blob/changes/wiki/en/en-Getting-Started.md
In my opinion, this should be on the homepage https://jamulus.io
Have a look at the new page. Is this enough?
This is already part of the sub-pages (Install for Windows/macOS/Linux)? Sure, we can do some changes here. |
|
I think I should clarify a little; I'm not advocating for adding anything new. The only changes would be that the content from Maximise Quality and _Having Trouble _ be moved to onboarding. To add, what I meant by "Description of Jamulus" was how it works (my bad). |
|
Here's my version of the page now. I've tried to streamline the information and added some formatting. Let me know your thoughts. |
|
Yes. This page looks more organized now. In the beginning, we had the "How Jamulus works" section right at the top but weren't sure if this might intimidate or confuse non-techy people. The recommended hardware section might be a bit misleading:
Could be a question somebody might ask. Are you sure we really want to move the "Minimize latency, maximize delay" section to the onboarding page? |
|
Furthermore, I'd like to make clear that you can use Jamulus without an external audio interface with ASIO4ALL and WiFi but that this will cause quality problems and therefore is not recommended. Otherwhise, some people might think "Ok. I can't use Jamulus since I don't own this special professional audio device thingy which is probably too expensive". |
|
The "How Jamulus Works" section might need some reworking, but I do think there needs to be some explanation of what Jamulus does (I remember @Erioldoesdesign mentioning that the client-server aspect isn't apparent). About the recommended hardware, the live site sort of already gives an imperative to the reader as it mentions. "Use an audio interface/external microphone, not your internal sound card", only after reading the body text do they realize that's not true. I think there should be a delineation of the minimum (what is needed to run and use Jamulus) and recommended (what is needed to have an optimal experience with Jamulus). I guess for ASIO4ALL and Wi-Fi, they could be mentioned in the minimum requirements as Audio Driver (specifying OS etc.) and Internet Connection. |
Yes. There's also an issue called "diagramming Jamulus": jamulussoftware/jamulus#64 This might give some more insight?
Yes. Probably it's too harsh a the moment. Since it's under "Maximize quality, minimize delay" we thought of this like a optional but strongly recommended section. But it seems as if this thought didn't come across.
Yes. That's a good point! If we can clarify this that would be great. |
|
I recommend thinking of getting new users through two stages. The first, the minimal hardware configuration. Then if they wish, how to optimize performance. Consider the minimal configuration for getting on Jamulus as USB gamer headset (includes microphone) and USB ethernet adapter and cable. This is relatively low cost and the least intimidating. Then the user is ready for a discussion of choices to get more performance. |
Yes. I agree for the website. Nevertheless, we're currently trying the contrary approach (and are still waiting for the interfaces which we ordered last year, to arrive). I don't want that these people need to tinker around with ASIO4ALL. It just caused problems for me. |
Thanks, I'll check this out.
I think we should be careful about the usage of the word "minimum". The documentation should be consistent in its usage and should only mean the least required. Thus, for hardware specifically, we could use "strongly recommended" for things like ethernet and wired headphones, since technically Jamulus could be run without them (albeit with a very poor experience). |
|
Speaking of minimum requirements, what are the other requirements (memory, HD space, audio driver?). |
|
HD space: roughly about 70mb for Windows, but I'd suggest more if you want to use recording. |
|
Just a note on the long-running issue of explaining how Jamulus works (and the related issue of the diagram): Beyond the demographic of curious engineers, I'm not sure anyone really cares how Jamulus works. Vaguely comparable software like Zoom, Dropbox or WhatsApp don't feel the need to push explanations of their infrastructure, edge routing or PKI at their users because (despite these things being important parts of the system), nobody needs to know, nor does anyone ask. But if they do, then I think it's reasonable to wonder why they would? What would they do, or how would they act differently if they knew that Jamulus was, for example, P2P and not CS, or that central servers don't carry the sound signals? It is for these reasons that I think hitting new users in the face with a technical diagram is a mistake. And I say that as the person who created that diagram :-) It makes Jamulus look intimidating. |
|
That makes sense. |
Yeah, I definitely agree with that. Would some kind of preview of Jamulus (screens of it in use) be better then? It would be beneficial to give presumptive users a peek into the interior. I know there's the wiki/demos page, but I feel like it's quite hidden at the moment. |
|
Yes - in fact we probably do need to use more screenshots generally. There's another ticket for this in fact but it has a bit of dependency on sorting it out so that we can deal with images without going crazy |
|
We certainly don't need to explain how Jamulus works to be at the top level for all users. However, it should be easy to know where to get this information. This information is to enable the more technical user to understand the inputs and outputs through the UI for troubleshooting. To be effective at troubleshooting, it is essential to know why. Currently, it is hard for me to know if the information I gather through word-of-mouth is well-grounded or not. (So here I am monitoring these threads.) |
Apologies, but while I don't disagree with that idea in principle, I don't actually understand it in practice. Can you give some examples of problems you might have when using Jamulus that would be soluble through such knowledge? By this I mean something like "When I hear [something], I would know to adjust [system thing]". Or do you mean something more like, "I can't hear [something], so knowing about [system thing] will point me to doing [action]"? I've tried to ask this question before but somehow never really get any clarity on it. |
|
@gilgongo we are both having trouble getting clarity. For me, looking at the puzzle from the outside, I wish to have clarity on what can be fixed. Currently, I spend most of my puzzle-solving on, why is the overall delay so high. It would be great to be able to isolate the problem to a particular part of the data flow (as demarked by buffer boundaries or something else). Part of this question is are buffers lost or just late. The next problem I want to address is why is there a loss of fidelity. It would be great to be able to identify where in the signal path the problem is occurring. Finally, how do we do this when we are not at the client (meaning some less technical user is having trouble. |
|
So if if latency is high (indeed for any given issue with Jamulus in fact), there are currently only a handful of things you can adjust to improve that: your jitter buffers, your sound card buffer, CPU or bandwidth hogs, switching servers or switching machines/hardware. In most cases, the only things you can practically do anything about are the jitter buffers and your sound card buffer settings (and maybe the small packets setting). The implication is that there might be some reliable connection between, say, a packet's lack of traversal of some part of the system and a remedial action like widening a sound card buffer. But is there such as connection? This is why I find hard to understand calls for more telemetry, flow diagrams etc. - how would more understanding change what you did? |
|
When the latency is high, I do want to know which of the handful of things need attention. I dislike the prospect of changing things experimentally to see if it gets better. Where I am, I see highly variable Internet performance. I would like to know if the problem is in the user's equipment or if it is the network. "Highly variable Internet performance" is a euphemism. It is hard to get network problems fixed without better data. |
|
Ok so I think I'd be clearer if we reframe the issue as whether there is a reliable cause/effect pattern: something in the system that can reliably indicate a specific problem area (eg network issue Vs audio hardware) and therefore an effective action to take (eg use better Ethernet cable Vs adjust audio buffer) to solve that problem. If there is such an indication, then we should pursue the surfacing of that. I don't know if that's possible though. It has been discussed a but I think though but never seems to get very far. |
|
That is the goal and it is hard. It is easier to have "test points" that can help a human isolate (or localize) the problem. There is a lot of awesome goodness in Jamulus. The technical (non-developer) users need tools to help Jamulus deliver. Most of the problems are caused by the users or the Internet. The model of what to do is to realize the user/developer intuitively knows what changes (adjustments) to make to optimize Jamulus operations. We need tools so that non-developers can do these tasks (which we call support). |
|
From what I understand though, it's not possible to help a human isolate the problem, because there is no connection between a perceived problem like "popping audio" or "drop outs" and a programmatic event like a packet being dropped, queued or arriving late. There are visual indications in Jamulus of programmatic events in the form of the delay and ping LEDs in the UI, but they're not actionable in the way you want because of my statements above. Does this make sense? Basically what I'm saying is that more "telemetry" can't help the problem of people not knowing which of the five things I've listed they need to tweak in the event of problems. Unless I'm wrong, you are, I'm afraid, doomed to blind experimentation in solving problems with Jamulus no matter how many logs, diagrams or flashing lights you have access to. |
|
You are mostly right. Dropped or late packets will always affect the audio codec. It is harder to connect because we might not hear the defect from a small (single packet?) defect. And a casual observer may not distinguish between different kinds of audio defects. This is hard with only human senses. While you are mostly right, the only reason I have been willing to help so many users with their problems is that I am hoping to acquire enough experience with Jamulus's behavior to help us all escape the need for blind experimentation. Jamulus is awesome. It would be even more awesome if it was easy to install and easy to support. |
|
When you say telemetry provides the only clues we have for troubleshooting, I disagree. Your ears are the only real clue. Everything else is (potentially) misleading. Be that as it may, you say you are hoping to acquire enough experience to help us all escape the need for blind experimentation. Do you think you've seen any cause/effect patterns (and crucially) actions that could be documented for the purposes of troubleshooting? |
|
I think we need to start by lowering any hesitation and showing that Jamulus is easy-> i.e. minimum needs, showing pictures of what users should expect (as is done in onboarding) and then mentioning how to upgrade. |
|
I would say that there's certainly a case for combining Getting Started and Onboarding, if only because the former was written first and may not sit well with the latter now perhaps. However, @dcorson-ticino-com I think there are probably two competing approaches to the problem of getting people started with software in general:
The rationale behind 2 is that there is also a phenomenon whereby people load a page full of (to them) very detailed instructions and think "Oh OK. This looks too difficult. Back to Google then ..." So far, we have been in the latter camp: brief "need to know" (Getting Started), then helping hand in the event of issues (Onboarding). But ultimately, this is a sort of "cultural" thing. Do we think our audience responds best to approach 1 or 2? Approach 1 is increasingly unusual. EDIT: It occurs to me that the overall "brand" of Jamulus is possibly one that lends itself to the first approach, which in turn attracts those who respond to approach 1, and perhaps repels those who don't? So far, this hasn't really been a problem, but as of the last couple of months, we are staring to appear in Google searches (following @ann0see work to get us off Github wiki and other search engine friendly moves). So that may change, ANOTHER edit (this is getting too long, sorry): Don't forget also that inducting choir members is a fundamentally different scenario to that of somebody coming to Jamulus for the first time. In the former case, if they can't use Jamulus, they're not going to be in the choir. In the latter, there is always JamKazam, NinJam, Jamtabaa, etc. |
|
Good thoughts. While we, of course, want to convince people to use Jamulus, we are not selling anything, we are offering good product and a helping hand to get started as easily as possible. I see there two very different worlds. I think we should not underestimate the reaction of people to a helping hand. |
|
I don't really agree that the commercial considerations of those systems are that relevant (they do in fact have very extensive documentation, should people wish to click on "help"). VLC is free. Tor is free. They are (arguably) rather more complex in some ways than Jamulus. In fact Tor a very good example of what I mean.
I agree, but my point is a "cultural" (perhaps even ideological) one. It starts from a fear that Jamulus will forever present itself as difficult. An engineer's tool. For people with high computing skills or knowledge of things like audio interfaces, mixing, "client" and "servers". For every well-meaning "helping hand" there is a possibility that it aggregates to slap in the face by mistake. Of course, we might legitimately say "Well, Jamulus is for those people - it's not easy to use, and needs to be explained." After all, our "shop window" as it were, isn't as sexy as something like Tor or Zoom. And that's a legitimate point. It's probably true for now. But I think we should not underestimate the reaction of people to that approach in the longer term. |
|
We do have a cultural bias that makes Jamulus difficult for non-engineering musicians. A lot of our solutions require being a server administrator. That is a big barrier for many people. Of course, there are a lot of people where administering a server is a basic skill. |
|
Well, server setup and maintenance is a specialist skill (beyond simply spinning up a small public server to see if that works with some friends - that's trivial). Fundamentally, you don't need to run a server to use Jamulus and when I wrote the server docs I was almost trying to make them sound complicated for that reason. But this is a totally separate conversation. |
|
"Well, server setup and maintenance is a specialist skill (beyond simply spinning up a small public server to see if that works with some friends - that's trivial)." Apparently, I have misunderstood the frequent discussions about spinning up a (small) public server for demo/test purposes. It was never clear to me that comments on how easy it is to just run a server were not a recommended (and routine) practice. |
I definitely agree with this approach. Currently, I think the content in the Getting Started page sits in a weird spot where different types of information with different values are presented to the user. For us, we know that this is pertinent information and we believe we must tell them as soon as possible, therefore we think the solution is easy: just put it at the beginning! However, new users, especially those that may come through a google search, will have significantly less time they want to invest. These new users are simply exploring and are in a discovery phase. When we start telling them at the beginning, "you need to do this, that and also this! but remember don't do this!", new users simply won't read it, or at most, skim the heading and forget it. If we want to provide proactive help (in the case of onboarding and setup), I believe that the best place to do that would be directly in the software itself. In my opinion, the website should allow users to get started quickly and also be the place where we can provide reactive help (FAQ, Troubleshooting, Documentation). At the moment, I understand that large UI changes in the software aren't entirely actionable (correct me if I'm wrong). That's why I'm advocating for moving certain sections of the Getting Started page to the Onboarding page. That way, we can better follow along with a user's task flow, while guiding them in the right direction. |
|
I do agree with @dcorson-ticino-com that "Onboarding" might be too HR. Maybe something like "Using Jamulus for the first time" would be better? |
|
Random thoughts... Try this as a first time user.
Why is it "Advanced" to "download now"? That immediately says: "TL/DR - go away" That "Get started now" should be "Download now", to an OS-detecting link that kicks off the latest download immediately. Then underneath it should be the "Get started with Jamulus" link or something like that. I'd also have the layout of the banner more horizontal, with the cloud to one side to the left of the rest, with the "Jamulus | Play music online. With friends. For free." a bit larger, taking up about the same space as the (now) "Download" and "Getting start" (whatever) link. The page is less likely to scroll then... I also think @dcorson-ticino-com's document is pretty good, but would indeed need a bit of work to make it appeal to the stand alone user. However, neither the current "Getting started" nor the "Onboarding" (name must change...) pages really get a user started. The best would be separate paths for each OS. Windows needing the most hand-holding, of course... Getting started should:
Getting started should not
|
|
I like the direction. Regarding "appeal to the stand alone user", many musicians are being introduced (pushed?) into Jamulus because their ensemble (chorus) will use Jamulus. They need to feel reassured when they first visit jamulus.io. |
|
I'm being off topic still.. Another front page point should be to feature "What are people doing with Jamulus?", and encourage projects to get in touch. |
|
@pljones Yes, I think this highlights the fact that the "journey" has been a bit too fragmented in its creation and your suggested modifications are good ones - if only because I have suggested some of them in the past :-). BTW as I've just said in another discussion (there are a lot of them): do we think it might be an idea (along with your OS-specific observation) of customising the new user journey by intended outcome? So if we established for example if they are a singer (mic only), or a singer/player (instrument + mic), and then acoustic instrument vs electric? Would that mean we could bypass certain problems or emphasise certain issues in the setup? For example, Rule Number One is of course far harder to follow if you are singing or playing an acoustic instrument.
Just so I'm clear - do you mean reassured by seeing information rather than just a download link? In other words the first approach I outlined in #250 (comment)? I think this discussion is solidifying around which "direction" we want to take on this. Re. "onboarding" feeling bad - we might be able to side-step the issue if we re-cast "Getting Started" as one page as per @pljones description of "Getting started should" here #250 (comment) |
|
I like the direction of this issue. When I say "reassured", I am thinking of the technically nervous musician. I just want to keep a focus on reassuring those musicians that they don't need to be a programmer or tech wiz to succeed in using Jamulus. |
Yes, although that's easier said than done because of the subtle issues around things like the natural tendency to want to "explain" in various ways (the diagram conversations just never end), the current limitations of Jamulus (eg it may not be possible to make it any easier to choose and configure the right audio interfaces), and "soft" issues around website design and presentation (limited resources to make a very comforting-looking website, and design efforts coloured by our desire to keep things collaborative as an open source project). But I think that we are getting there, and @pljones suggestions seem to me to be the most lucid so far. |
A comment to your guide. Add a point to ask people if they can hear any sound from YouTube or the like. Or if they can use zoom. First make sure the equipment is working. (Close Jamulus though, they don’t work at the same time). In fact, if they can use zoom (many people do in these times) they can use Jamulus. And more than once I told people to raise the normal Windows audio level when they couldn’t hear us in Jamulus. Didn’t occur to them. And there is the issue with the unsigned installers. People see scary messages of dangerous downloads and so on. I know why but they need to be encouraged to try anyway. |
Absolutely. No 1 is out these days. People don’t read anything. I am not much different. Stuff just has to work (and Jamulus does!). ...
Correct. I am in the choir camp and there most people are afraid of computers. |
|
@Hk1020 OK so I think we are gaining agreement around PLjones's prescription in #250 (comment) BTW one thing that hasn't been raised this time around is the issue of "beginners vs power users". It has been suggested in the past that we divide the docs along those lines, but I am generally opposed to that approach as I think in practice it just gets confusing and difficult for various reasons. |
|
There are "first time users". I think we're all agreed that, whether they're "power users" or not, they want a very easy way to get the software actually running so they can see what it's all about. That needs to be made as simple as possible for everyone. Just to note on that -- it also needs to be made as simple as possible for people who are "pure MIDI", i.e. no audio in to their computer. I'd break that out onto a separate page though, early on in the process. Those users are probably already more advanced and able to handle more complex problems. But still catch them early so they feel welcome and supported. Beyond that, many users won't want any more - so long as when they play or sing, they're hearing and getting heard, they're done. Anyone who does come looking for more could probably be called a power user of sorts. But not all power users are technical. Most just want solutions to more complex problems. So there's the "how to guides". What questions are most often asked? "How do I set up with Zoom?" etc? Each of those could end with a "how it works" section so the real power users can understand it and adapt it. Oh - not to stay on topic too long... - and there should also be a more extensive "How to get involved" section, especially with the re-organisation. It currently feels like you need to be a developer. It could have sections on:
|
Hey! I need this quick, I didn't even know there are automated checks ! |
|
The word "Contribute" is on the home page (and the footer of each page after that). It has a link to this page, which I guess could be improved (in fact I think we have a version of it on a branch somewhere?) These is also this page, but I can't remember where it's linked from (which reminds me, I think I may just go in and manually restore all the breadcrumbs we lost when we moved from Github wiki). Maybe it got forgotten? If somebody wants to write a Jamulus code submission HOWTO with stuff like what compilers and builds to use and keep that up to date, then that might be a good idea. I don't know as I'm not an engineer. BTW I'm a little circumspect about promoting efforts to invite contribution since it may imply we can digest all submissions, triage and de-dupe stuff properly. Which we can't really. But maybe that's just the nature of things. |
"Contribute" can means "give us money". It's not a terribly inviting word and, as a single word, a bit stark. And yes, it was the existing page I was suggesting could do with an overhaul, but I'm freely admitting that's out of scope here..! :) |
A separate issue, really - leadership need not be about doing, it can be just about guiding and helping those who do, do well. I think the spirit of openness needs to be pervasive. There should be no feeling that people are excluded from being involved. Perhaps the best some could do would be to triage issues - going through reported bugs to ensure they're properly documented and real, etc, clarifying requests for new features and so on. |
That's certainly one meaning of the word. Unfortunately, all other synonyms in English have the same connotation (help out, donate, chip in...). It's sufficiently contextualized on the homepage to avoid confusion. Otherwise, I'm at a loss to come up with anything that means non-fiscal contribution of resources :-) |
Indeed, I make no distinction. As to pervasion of openness, I assume (but I could be wrong) that if people know anything about FOSS then the will be in no doubt about that. The subject of management in general is the subject of an upcoming f2f discussion though. This sounds like one for the agenda (once date and time are agreed). |
|
catching up with the discussion from @Hk1020 (5 hours ago at this writing). There is another way to merge 1 and 2. In both cases, the user goes straight to installation, and then there needs to be a clear problem resolution path for any issues that arise. In this path, Jamulus must self-diagnose the problem and tell the user what needs to be done to resolve the problem. My plan B is to take the user through a step by step preinstallation check to ensure Jamulus does encounter a problem and then a step by step configuration of Jamulus. Clearly, plan B does not work if the user will not read and follow all the steps,. Helping users with their install problems is no fun and getting very old. |
Is your feature request related to a problem? Please describe.
Currently, I think the "Getting Started" page contains information irrelevant to getting started. For new or potential users, this page is probably the first page they click on after the home page. Thus, it addresses users that have not yet or are about to download and install the software. Therefore, sections like Maximise Quality and Have trouble? Can't keep in time? don't have relevance to the reader since they might not have even used the software yet.
Describe the solution you'd like
The "Getting Started" page should ideally contain:
Maximise Quality, Minimize Delay and Having Trouble? Can't keep in Time? sections can be incorporated into the Onboarding page, describing an optimal first-time use of Jamulus.
In context, the flow for a new user would go from Getting Started (Check Hardware + Specs, determine if they can use Jamulus) -> Set-up on their OS (Follow installation steps and setup hardware) -> Onboarding (Learn to use Jamulus optimally)
The text was updated successfully, but these errors were encountered: