Re: gnome-bluetooth documentation validation

[Baptiste Mille-Mathias <baptiste millemathias gmail com>]

On mar., 2009-06-30 at 23:27 +0200, Milo Casagrande wrote:
> Hi Baptiste,
> 

Hey Milo

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


> 2009/6/29 Baptiste Mille-Mathias <baptiste millemathias gmail com>:
> >
> 
> 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).

what markup could I put to insert a changelog in <revdescription>? Using
the existing <para role="..."> is not giving a nice output.

> 
> 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.

bummer, I don't know why I pasted 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
> can:
>  * 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.

I also added some actions now.

> 
> 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)?

Both will trigger the same menu

> 
> 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.

Okay, when writing these sections, I was a little out of explanation as
I thought they were self-explanatory.

> 
> 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...

"Last used devices" part in the applet is not just for viewing but also
permits to quickly do actions like connect, send, browse, ... with know
paired devices. 
The screenshot is a little bit outdated, as now each devices has a
sub-menu with its related possible actions.
I'll extend and correct this part.

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

I corrected that, you're true that should be avoid. 

> 
> 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?)

What is the default theme to use, I took clearlooks.
> 
> 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.
> 
> Ciao.
> 

Thanks for the patch, I applied it.
I'm going to give a review with your comments.

Thanks a lot

Where should I put my changes, should I commit it to gnome-bluetooth, or
should I put in gitorious for review?

-- 
Baptiste