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
On 10 December 2012 19:47, Christopher Antila crantila@fedoraproject.org wrote:
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!)
Thanks for the feedback, I've amended my contribution as suggested. If I have time later in the week I'll try and put the rest of the page into line.
However:
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.
I'm afraid I don't agree with this. Someone whose first language is not English is not the equivalent of a five-year old. There are many differences in their ability to comprehend abstract concepts or to deal with idiomatic ideas. Actually your suggestion (which I've added) actually shows this:
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."
The problems a five year old would have are not the ones a non-native speaker would. They might both have difficulty with the slightly abstract idea of 'gain control of' rather than owns, but a five year old may be more confused by the metaphor of owning, whereas a foreign reader might find the simpler verb easier to understand. I'm happy to make revisions for clarity or easier reading, but someone else will have to do the dumbing down if that's what's wanted. </rant>
-
Christopher Antila -
Ian Malone