Brevity: Too long vs too short about jamuluswebsite HOT 12 CLOSED

Footnotes would be an efficient way to point to in-depth details.

from jamuluswebsite.

I know writing documentation can be uninteresting to the experts. I have been struggling to make the transition from a casual user to an expert. I am interested in seeing three kinds of information. (1) How to.; (2) Why - this will help me solve problems appear; and (3) Where to find more information. Thanks.

from jamuluswebsite.

Yeah. I'd say these are the main points. Well said. This would then (in my opinion) lead to the conclusion that we only have to explain a little bit in the text but add e.g. more footnotes?

from jamuluswebsite.

we should agree on a general "What is too much, What is not enough" policy.

"Getting started" is a very different thing from, say Troubleshooting or the Privacy Statement, so I think it depends. Introductions should be as short as possible really, if only because lots of words early on signifies that the thing is going to be complicated. But in principle, Jamulus isn't complicated compared to a DAW or retirement investing, for example.

It would allow contribution like tips/tricks/guides by multiple people which would like to publish there information etc and would reduce links/unneeded edits.

Would only those contributing be able to use Jekyll? Probably more inclusive to create a new forum group for this, perhaps. I'm also a bit wary of hosting information on the "official" website that we might not be able to verify or maintain. And it's not as if there isn't already a lot of "unofficial" information out there on the web for people to read :-)

If I were new to Jamulus, I wouldn't understand why I am "strongly advised to use an audio interface".

Perhaps. But your suggested text could equally result in them asking "What's an infernal sound card? Have I got one? How do I know??? Why would I want to use a USB microphone with my Telecaster?" or similar reaction.

It's worth remembering that out of 183 people surveyed so far since the start of August, 56% found it "Easy (installed and got it going almost immediately)", 34% said it was "A little tricky (needed a bit of work, but worked it out after a while)" and 5% found it difficult and had to read more docs to get going.

Would be good to try some variations in the wording though, certainly.

from jamuluswebsite.

@gilgongo I have had a lot of trouble onboarding some musicians. Most troubles are (1) getting a window user configured and (2) trying to understand if the bad quality (mostly from delays) is in the user's computer or from their network link. I have had a lot of friends give up because the quality is bad (and it is too hard for them to find and fix the cause. From my experience, I suggest the "5% found it difficult" underrepresented the problem. Your survey cannot measure all the people who think Jamulus is either poor quality or unusable.

I find the tips very limited in usefulness. When I have a problem, it is often impossible to know if the tip is relevant or not. Knowing why helps me analyze and fix a problem. Too many users are willing to just fiddle and change settings with no clue if it will help. I find it frustrating to have 5 tips and not know why one should work. The tip writers never explain why you should use their tip. "It worked for me" is not a satisfying explanation. How do I know if it is just superstition?

Sorry.... I am very frustrated with tips that only sometimes work.

from jamuluswebsite.

@gene96817 I don't doubt people have problems, and as you point out there are some common areas that people have which are hard to fix. Unfortunately, the extremely wide (in fact almost infinite) variety of hardware, software, skill and expectation combinations makes it almost impossible to be prescriptive about fixes. So the next best thing is the "try this" method that may or may not work.

The survey is of course imperfect, but it's the best non-anecdotal data we have (I don't see why it would exclude those who think Jamulus is poor or unusable). But my point is not that we should ignore the 5% or not try to explain Jamulus better. It's simply that we should present Jamulus as being easy at first, then allow people who don't find it easy to get some help after that. I'm sure you don't imply that we present new users with a troubleshooting page from the start, for example.

Basically, with Jamulus in its current form, we have to accept some limitations on what's possible to achieve with documentation alone. Efforts to enhance Jamulus will pay dividends I think. For example @ann0see has suggested perhaps a setup wizard for Windows users which implies some specialist coding to probe the status of sound devices. This would guide the user in configuring their system according to what it finds. Others have suggested simplifying the way sound devices are listed, or trying to emulate the way things like Zoom and Meet present devices to select, etc.

from jamuluswebsite.

@gilgongo Thank you for your reply. I am in general agreement. My main point is explaining why goes a long way to cover all the variations. (After all the principles are the same in all cases. The details obfuscate the problem.) The "try this" scattershot method works for users that just want things to work without much thought. It works when it works and it fails when the suggestion is only close. I appreciate everyone's hard work.

If I could find information on the theory of operations, I could help with documentation or some other issues. Right now I am trying to figure out how to onboard users and teach a few others how to distinguish between client issues vs. network issues.

from jamuluswebsite.

Right now I am trying to figure out how to onboard users and teach a few others how to distinguish between client issues vs. network issues.

I don't know if it's possible to pin down specific sound issues to specific actions. Can you explain what you mean by "If I could find information on the theory of operations"?

BTW this is not to say that I don't think we could get closer to an "if this, do that" style of presentation but just that I don't know how feasible that is myself.

from jamuluswebsite.

By "theory of operations", it would be great to have a document that is a road map of the Jamulus code modules and data flow. Maybe I am just a very naive coder and I am failing to learn what I need from the code. A road map of the modules and data flow would go a long way to interpreting problems.

It would be very difficult to write an "if this, do that" troubleshooting guide. I am not suggesting that.
Knowing where a "knob" is connected to the dataflow would make it much easier to diagnose user-created problems and how to optimize behavior. It drives me crazy watching users just blindly twidling the controls.

from jamuluswebsite.

Could you give an example of such a document? Like a lower-level version of this diagram perhaps?

from jamuluswebsite.

Getting to theory-of operations might be too big a jump from the diagram. A good next step would be to show where all the user settings go and where all the status displays come from. It would also help to see in this diagram the low of the audio signal from the ports, through the OS, in and out of Jamulus. What this does for me is to explain (a) where an adjustment (user input) affects the signal flow and (b) what a meter is showing of the signal flow. Similarly, information about the buffers and delays are more useful when we know where it is connected to the digital data flow is happening.

From an audio perspective, it is useful to know where the volume adjustment is happening.
From a data perspective, it would be helpful to know which buffer is being managed and where you are measuring delay. I understand the effects of buffering, queuing delays, and buffer underrun. It would be helpful to then anticipate the interaction of the buffers in Jamulus and the buffers in the OS. I do wonder which OS buffers (or OS modules) are being used. It would let me anticipate the impact of other processes that are running. (Yeah, you could say only run Jaumulus and shut everything else down. That is a bit extreme.) Most of all, I can then better understand how choices a user makes affect sound quality and the quality of the Jamulus experience.

Thanks, Gene

from jamuluswebsite.

I think we are going a bit off topic now. This issue should not focus on simplification of the Jamulus Software (this should be discussed on the normal jamulus repo) but on the documentation. I agree, that there are some issues (mainly setting up the audio correctly especially on windows) but these can not be fixed in 100% of the cases.

The documentation and of course Jamulus should be easy to use. This does also mean, that the user must know (not in detail) why he has to do specific things, at least in my opinion.

E.g. for the section how jamulus works:

1. A first time user doesn't have to know how jamulus works in detail (e.g. he doesn't need to know about audio buffers on the server, how to setup a server etc.)
2. He does need to know briefly that in order to start jamming, he must connect to a server (but he doesn't need to know about central servers). This information doesn't have to be prominent but everybody should know it. It can be somewhere on a "How to use Jamulus" site which explains how to connect to a server and that's it.

For the setup I do agree that some things could be too much. But at least we have to explain that audio quality will improve if he uses an audio interface, LAN, minimizes internet traffic etc. and should also keep in mind that a first time user will probably not fulfill these requirements (Problems already begin because they don't want a LAN cable/don't even have a lan input on their laptop, Audio interfaces are even less common). The user should know why these things are required. If he doesn't he will probably blame Jamulus for bad quality.

I think, we should move a lot of information to footnotes.

from jamuluswebsite.