Hi: On 9 December 2012 22:21:44 Brendan Jones wrote: > On 12/09/2012 09:52 PM, Ian Malone wrote: > > Made some updates to > > https://fedoraproject.org/wiki/JACK_Audio_Connection_Kit#Integrate_Jack_wi > > th_Pulseaudio > That's great Ian. Thanks Agreed! I'll steal some of these things back into the Musicians' Guide when I get a chance... which should *actually* happen next week (gasp!) I would like to offer some simple suggestions for revision: 1.) Always use the same, correct name for everything. "JACK" is always "JACK" and never "jack" or "Jack." It's "D-Bus" not "DBus." It's "PulseAudio" not "pulse" or "Pulse" or "Pulse Audio" or "Pulseaudio" or "pulseaudio." This helps less experienced users and non-English readers know that you are always talking about the same thing. If I've never used Linux before, how am I supposed to know for sure that "DBus" and "D-Bus" (for example) are the same thing? 2.) Technical words should always be formatted distinctly: application/program names (like QJackCtl), system components (like JACK), filenames (like /etc/security/limits.conf), commands (like "ulimit -a"). On the Wiki, the Documentation Project's standard is that program names are italic, system components are bold, filenames and commands are fixed-width. 3.) Write like your audience is five years old. For one thing, they could be. More likely, especially as English speakers, we have to keep in mind that there are a lot of people whose first language is *not* English and who may only have the English skills of a five-year-old (however intelligent they may actually be). We want them to be able to use our documentation too, so we should make everything as simple as possible. This is by far the hardest part for me. As an example, consider the first sentence of "Integrate Jack [sic] with PulseAudio": "Jack will ask Pulse Audio through D-Bus for ownership of the sound card." I know exactly what that means, but consider it as though you were five. First question is "who is Jack?" Even if it were "JACK," this sentence treats some software as though it were a person. Software doesn't "ask" for things, and cannot "own" things. Plus, the "through D-Bus" part is a little awkward. I propose an alternative: "JACK uses D-Bus to gain control of the sound card from PulseAudio." It's still not great, but it's a little better. All of that being said, I appreciate your work here, and I obviously understand that the wiki is a place where things are *supposed to* start out rough and get polished up later. I especially like the level of detail you put here, as evidenced by the multiple options in the "Integrate..." section, and that you clearly intend to recommend DBus as the "best choice" when it eventually works. So keep at it! Further contributions on this or other topics would be greatly appreciated! Christopher
Attachment:
signature.asc
Description: This is a digitally signed message part.
_______________________________________________ music mailing list music@xxxxxxxxxxxxxxxxxxxxxxx https://admin.fedoraproject.org/mailman/listinfo/music
