Re: gnome-bluetooth documentation validation

Hi Baptiste,

first of all, thanks for helping us out writing documentation.

2009/6/29 Baptiste Mille-Mathias <baptiste millemathias gmail com>:
> So I wanted to know if some people could have a look at the
> documentation and provide feedback and correction, because I'm sure it
> could be improved.

I took a look at the document and I'll report here my thoughts.

(I'll write down the notes I took while reading the document, so they
might look like chunk of discussion.)
(I'm also attaching a patch with some of the modifications I suggested
here, take a look at it.)

In the revision history, the "version" of the manual is actually
wrong. As a GNOME Doc convention, the major number of the manual
should respect the major number of the GNOME Desktop (in this case 2),
while the minor number if is the first version will be zero.

So, to sum it up, the version should be 2.0 (if in the future you'll
update it, it will probably be 2.1 or 3.1).

I see that in the XML file you copied the text of the license. It is
not necessary: you defined the 'legal' entity at the top of the file,
you just need to use the '&legal;' syntax and that's it.

In the Introduction section, what do you think of rewriting it as follows?

gnome-bluetooth is an application that let you manage Bluetooth
devices and connections in the GNOME Desktop. With gnome-bluetooth you
 * Send files to your Bluetooth devices or browse their content.
 * Connect to your devices, like headset or audio gateway.
 * Add and delete Bluetooth devices or manage their permissions.

The titles of the various sections should be in title case, usually
with words > 3 characters in capital letters.

In the 'Bluetooth Applet' section you use different terminology for
"notification area": notification applet, notification tray,
notification zone. There shouldn't be a "best way" to call it, but as
a suggestion, I will say 'notification area'. Anyway, I think it will
be better to use on single  it only in one way.

Usually, when talking about actions with the menus, it's better to use
the verb 'to choose'. So, instead of 'open menu', it should be 'choose
Applications...'. I'm also a big fan of task-based approach, so in
this section I will split up the small chunk of information into two
numbered lists.

When you talk about turning off the bluetooth adapter, you say "Click
on the icon". Since I don't have the opportunity to test that version,
is it a primary click (left click) or secondary one (right click)?

In this case, since it's a pop-up menu with prefixed values, it's
suggested to use "select". Even the menuhcoice tag here in this case
is not necessary, it's not a sequence of different menus, better use
the guimenuitem tag.

In the "Sending files to a Bluetooth device" you say "Choose this
menu", I think you are referring to the title of the section as the
name of the menu. IMO, this is not a good practice. It's better to
tell user the exact name of the menu in the paragraph. This applies
also to the section following this one.

I don't understand the "Last Used Devices" section.  You say it's a
"section", probably in the menu (looking at the screenshot), but from
my POV, is not very clear. From the image I see a "Device" kind of
section, I will probably rename the section into something like
"Viewing the Last Used Devices", and explain that they are visible
form the menu and so on...

Wizard is a word that should not be used: the recommended word is "assistant".

The second and the third screenshot do not have the default theme
(actually it's lacking the theme at all) and there shouldn't be a drop
shadow on the image. In the third screenshot there are also part of
the French (?) translation of the interface (stock buttons?)

For an action over a button, it is recommended to use 'click' or
'click on', not 'choose'. It should be: Click on Forward...

I'll probably take another look at the document, but first I would
like to hear your thoughts and what I wrote here.


Milo Casagrande <milo casagrande name>

Attachment: gnome-bluetooth.diff.gz
Description: GNU Zip compressed data

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]