Comments (12)
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:
- 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.)
- 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.
Related Issues (20)
- [Next-release] List not showing correct in translated webpages HOT 2
- [Next-release] Translated copyright text not showing HOT 4
- [Next-release] Incorrect link in Running a Server page HOT 1
- [Next-release] Incorrect text in Running a Directory page HOT 1
- Fail CI build if Index file has wrong or no language tag set
- --directoryaddress replaces the --directoryserver command line option
- Interim rendering HOT 11
- Translation wrongly split on newly updated homepage HOT 9
- Add documentation for Debian repository HOT 2
- Remove hint for `--cleanuplegacyfadersettings` HOT 1
- [Bug] Quick Download text contains non-translateable text in next-release branch HOT 2
- [Translate] Adding NL images for 310 to repo HOT 3
- Reference text for server option not matching language used in the app HOT 16
- Text for Device/Audio Device in settings tab does not match with the application HOT 11
- Ideal link for headless server operator HOT 1
- [Typo] on wiki Installation-for-Linux HOT 1
- [Typo] Bad command line in french wiki Running-a-Server HOT 8
- [Bug] hreflang codes contain unrecognised undersores HOT 10
- Missing PipeWire config, only JACK in "installation for Linux - Set up your hardware". HOT 1
- Update iOS page as soon as sideloading on iOS/EU is available HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from jamuluswebsite.