Re: [RFR] templates://vpb-driver/{libvpb0.templates}
[Please CC me with any replies, I'm not on this list]
On Sat, Aug 01, 2009 at 09:15:27AM +0200, Christian Perrier wrote:
> Rationale:
> --- vpb-driver.old/debian/libvpb0.templates 2009-07-24 12:56:52.658486944 +0200
> +++ vpb-driver/debian/libvpb0.templates 2009-07-28 12:39:47.304330371 +0200
> @@ -6,5 +6,6 @@
> # phone in the region you are translating for, without any "long distance call"
> # prefix numbers that are specific to the telephone exchange being called from.
> _Default: 61
> -_Description: Enter your ITU-T telephone code (eg. 61 for Australia, 33 for France):
> - Configure locale specific options for Voicetronix hardware.
> +_Description: ITU-T telephone code:
> + Please enter the prefix someone would dial to make an international call to a
> + phone in your region.
>
> This is not "my" code....but rather the code used in my
> region/area/country. Use the long description to put the right
> explanation and use the synopsis as a prompt.
Ok, the "my/your" critique seems valid, but I think you've also removed
all the _actually_ important information for users here too :)
In particular this:
"Configure locale specific options for Voicetronix hardware."
and also the examples.
The important point here is that this is actually used to configure the
electrical specifications and other conventions of a specific piece
of hardware. It's not a general question about prefixing telephone
numbers, and in fact will never be used for that at all. It's also
not a general question that is shared by other things that may actually
care about the prefixing of phone numbers, so I think this makes it
misleading, both to the people it's intended for, and others who may
not actually (need to) care about it at all.
My apologies if the translator notes there were in turn misleading,
but those were intended to guide translators about making suitable
substitutions, not to guide users on how to answer the question.
(feel free to suggest tweaks for those too though if they might be
improved for the people using them)
The correct answer here may not even be related to your phone number
at all (if you are connecting this hardware directly to foreign
equipment). What we want to know is which region's standards to use,
the ITU prefix is just a reasonable, and somewhat understandable
approximation of that, and what the underlying code uses to switch on.
The examples I think are important, because even people familiar with
phones can get confused by exactly what prefix means what. And saying
this:
> + Please enter the prefix someone would dial to make an international call to a
> + phone in your region.
Is also wrong and misleading, because in most (all?) countries, there
are a string of additional digits that you need to dial before you even
get to enter the prefix part that we are looking for here. Since they
are _also_ different from region to region, we can't just strip them
off, we need people to enter just the bit that represents their region.
Now if someone can distill all that into a nice one-liner, we'll have
a good description :)
Telling people that this is a question for the Voicetronix hardware
at least gives them some context for what the correct answer should
be (and they can refer to our docs for further details on that).
Giving them examples that should be familiar in their region will
help with that I think. (I expected those also would be substituted
for other examples in any translation)
> --- vpb-driver.old/debian/control 2009-07-24 12:56:52.650487253 +0200
> +++ vpb-driver/debian/control 2009-07-28 12:41:02.752329819 +0200
> @@ -9,7 +9,7 @@
> Package: vpb-driver-source
> Architecture: all
> Depends: module-assistant, debhelper (>>4.0.0), make, bzip2
> -Description: Source for the Voicetronix telephony hardware drivers
> +Description: Voicetronix telephony hardware - drivers source code
> This package provides the source code for the Voicetronix kernel modules.
> Kernel source or headers are required to compile these modules.
> .
>
> Use a standard synopsis layout...
What exactly is the standard format you are looking for here?
As a native english speaker, that reads much more awkwardly to
me, uses most of the left of the line on perhaps the least
important (or at least, least unique) information, and drops
a plural kind of uncomfortably in the middle.
I'm happy to follow a form, but I think we can improve on the
above. It reminds me a bit of the govt. state supply catalogues
here, where to order a box of tissues you need to know that the
order number will in fact be found indexed under:
Wipers - paper, facial, for the use of.
> I think it would be interesting to have a boilerplate that better
> describes what are these Voicetronix things...but as I have no clue
> about them, I can't cook one.
It's telephony hardware, made by Voicetronix :) I can whack a URL
in there if it would help, but I have tried to avoid gratuitous
advertising except where mentioning the 'brand' is needed for
people to know the context or appropriateness to what they have.
What sort of boilerplate do you have in mind?
> -Description: Voicetronix telephony hardware userspace tools
> +Description: Voicetronix telephony hardware - userspace tools
This one is kind of the same, what does the hyphen add except to
break a natural phrase into something that seems stuttered?
> -Description: Voicetronix telephony hardware userspace interface library
> +Description: Voicetronix telephony hardware - userspace interface library
Here it doesn't seem quite so stilted, but again, what does the
hyphen add, except line length :)
> -Description: Voicetronix telephony hardware userspace library development files
> +Description: Voicetronix telephony hardware userspace - development files
Here you seem to have dropped the wrong word. It's a "userspace library"
(as opposed to the kernel space code). You've left just the adjective
and dropped the thing it referred to :)
> -Description: Voicetronix telephony interface library documentation
> +Description: Voicetronix telephony interface - library documentation
Reads ok, modulo the useless-use-of-hyphen query as above.
Anyhow, my own critiques aside, I'm grateful for the review,
if people have better suggestions I'll be happy to hear them.
Thanks!
Ron
Reply to: