On 10 December 2012 19:47, Christopher Antila <crantila@xxxxxxxxxxxxxxxxx> 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> -- imalone http://ibmalone.blogspot.co.uk _______________________________________________ music mailing list music@xxxxxxxxxxxxxxxxxxxxxxx https://admin.fedoraproject.org/mailman/listinfo/music
