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 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. 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. Ciao. -- Milo Casagrande <milo casagrande name>
Attachment:
gnome-bluetooth.diff.gz
Description: GNU Zip compressed data