Simplify the Getting Started Page

[mulyaj]

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:

• Description of Jamulus
• System + Hardware Requirements
• Recommended Hardware (Audio Interface and/or USB mic)
• Links to installation/set-up on Windows/Mac/Linux

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)

[ann0see]

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

Description of Jamulus

In my opinion, this should be on the homepage https://jamulus.io

System + Hardware Requirements

Have a look at the new page. Is this enough?

Links to installation/set-up on Windows/Mac/Linux

This is already part of the sub-pages (Install for Windows/macOS/Linux)?

Sure, we can do some changes here.

[mulyaj]

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).

[mulyaj]

Here's my version of the page now. I've tried to streamline the information and added some formatting. Let me know your thoughts.

[ann0see]

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:

Do I need an USB microphone and an interface?

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?

[ann0see]

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".

[mulyaj]

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.

[ann0see]

The "How Jamulus Works" section might need some reworking, but I do think there needs to be some explanation of what Jamulus does

Yes. There's also an issue called "diagramming Jamulus": #64

This might give some more insight?

"Use an audio interface/external microphone, not your internal sound card", only after reading the body text do they realize that's not true.

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.

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).

Yes. That's a good point! If we can clarify this that would be great.

[gene96817]

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.

[ann0see]

The first, the minimal hardware configuration.

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.

[mulyaj]

There's also an issue called "diagramming Jamulus"

Thanks, I'll check this out.

the minimal hardware configuration

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).

[mulyaj]

Speaking of minimum requirements, what are the other requirements (memory, HD space, audio driver?).

[ann0see]

HD space: roughly about 70mb for Windows, but I'd suggest more if you want to use recording.

[gilgongo]

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.

[trebmuh]

That makes sense.

[mulyaj]

hitting new users in the face with a technical diagram is a mistake

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.

[gene96817]

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.

[gilgongo]

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.

[Hk1020]

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 also turn the "onboarding" page into "Getting Started" or "First Steps" with the program installation now in getting started as a link to "Program Installation" or such as that is really not the problem.
BTW "Onboarding" is horrible "Human Resources" talk and not fit for use among normal human beings IMHO (immediate association waterboarding).
I am attaching my "Setting up Jamulus in Five Steps" guide that I have been using successfully. It is targeted just to the orchestra I play with, but I think shows how easy it is to start out using Jamulus.
JamulusQuideEn.pdf

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.

[Hk1020]

However, @dcorson-ticino-com I think there are probably two competing approaches to the problem of getting people started with software in general:

1. Tell them what they need to do comprehensively, but as briefly as possible (I would say this is the approach in your "Five Steps"). If they read and follow the guide, the chances of subsequent problems will be minimal.
2. Assume they won't read much more than a few lines before they double-click on the installer in anticipation of everything being easy. Provide a guide for them to use if - and they may not - have problems. This is the approach that most large or commercial projects take (Zoom, or Plex for example whose "Getting Started" are pretty much just download buttons).

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 ..."

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!).

...

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.

Correct. I am in the choir camp and there most people are afraid of computers.

[gilgongo]

@Hk1020 OK so I think we are gaining agreement around PLjones's prescription in jamulussoftware/jamuluswebsite#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.

[pljones]

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:

• "How to raise a new idea" (check it's not already done, check it's not already raised, check if it's likely to get accepted - read the guidance notes, etc)
• "How to report a bug" (check you're on the latest version, check the server is on the latest version, write down the steps to reproduce the bug, say what you expected to happen, say what actually happened)
  those two shouldn't just be on the templates: the guidance needs to happen first, the templates are reminders
• "What to do if you have a code change to submit" (check if it's likely to get accepted - read the guidance notes, make sure it's passing the automated checks).

[dcorson-ticino-com]

"What to do if you have a code change to submit" (check if it's likely to get accepted - read the guidance notes, make sure it's passing the automated checks).

Hey! I need this quick, I didn't even know there are automated checks !
I am simply using QT Creator, is that the right compiler ? build ?
I have found no info what I should be doing, but maybe I am blind.
Please point me in the right direction.

[gilgongo]

@dcorson-ticino-com @pljones

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.

[pljones]

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?)

"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..! :)

[pljones]

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.

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.

[gilgongo]

"Contribute" can means "give us money".

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 :-)

[gilgongo]

need not be about doing, it can be just about guiding

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).

[gene96817]

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.

[mulyaj]

Hey everyone, going to revive this discussion a bit.

I've made some changes to the installation page for Windows and to the Navigation bar in order to make the instructions as concise as possible and also tried to make the setup flow very clear. In the navbar, I've also turned the Onboarding page to the Getting Started page and am looking to add additional instructions as per @pljones's suggestions.

Let me know your thoughts.

[pljones]

Random thoughts. We need to move away from The "Central Server" - it's day has past by coming up to a year - so the graphic needs changing. It also has the old client/server logo, rather than to two separate ones, so it's an opportunity asking to be taken :).

Windows Setup macOS Setup Linux Setup -- that list of links needs splitting into visibly discrete parts. It looks like the "Other guides" and "Footnotes" didn't render right, either. So I'm wondering if it's just viewing it as the git-ified .md file that's the problem (rather than inside the wiki). Is it possible to preview as wiki-fied?

[mulyaj]

Right, when I was writing it I didn't realize ASIO4ALL had updated their page.

[pljones]

Yeah... the dates are pretty recent. It had been dead for years. Suddenly seen the annual traffic bill for the site, I guess, and either decided it needed to cover its costs or could be a source of ad-rev...

[mulyaj]

To clarify - would these changes be something we could implement? Specifically, for setup (referring to my branch), we could apply the Requirements -> Installation -> Audio Setup approach to each OS. In addition, remove the current Getting Started page; moving its content to the current Onboarding page, making that our new Getting Started page.

Then, the task flow is very straight forward: Downloads -> Setup -> Getting Started

[pljones]

I hope so - it's not going to happen for a while, until after the 3.7.0 is out, as it would need the translations for the new content, too.

@gilgongo @ann0see -- any input here for @mulyaj (specifically on timelines, I mean)?

[gilgongo]

I'll need to take a refresher course on the thinking on the 72 comments on this, but once I've got my draft for discussion out on the Contribution stuff jamulussoftware/jamuluswebsite#314 (which BTW is nearly ready might get that done next week) I was going to have a look at this one too. So, um. in a couple of weeks? (first draft for discussion that is)