[Fedora-music-list] new spin compose / fix to favourites
Christopher Antila
crantila at fedoraproject.org
Mon Dec 10 19:47:15 UTC 2012
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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.fedoraproject.org/pipermail/music/attachments/20121210/1289f4fd/attachment.sig>
More information about the music
mailing list