Hi, I would like to create a small style guide for whatsthis. Currently, there is no reference guide for them. After getting your feedback, I will submit it to the usability list. Here are some points I think we should include, feel free to add more:
Writing guidelines: Content: - As yourself what information the user needs to understand and perform the tasks. The whatsthis should be relatively short, but not obvious. Tell something the user does not know. For instance, when documenting list boxes or drop down boxes, try to explain each entry in the list (if the list is not too long). Rationale: The point of the whatsthis is to avoid the need to read the handbook. - Avoid explaining the actions or options using the same words or expressions as the dialog you are documenting. For instance, to document a "save" button, instead of "Click here to save the document you are editing.", use something like "Click here to *store* the document you are editing. If the document is new, a dialog box will pop-up, allowing you to enter a name and select the folder where your document will be stored. If the document was saved before, the current version of the document will replace the previously stored version." Rationale: the user who asks for help in the "save" button, a basic component of KDE user interface, probably don't know what save is. It is much harder to write whatsthis when you avoid using the language from the dialog, but it is also much more helpful. - When reffereng to another dialog or widget, try to be explicit. What is obvious for you may not be so easy to the reader. For instance, instead of using "Click here to edit the selected item.", use "Click here to edit the item selected in the list box above." - "Writing is to cut words": use direct and simple explanations. - We can use a lot of the writing tips lauri wrote for the docs too. Style - All the widgets should be named using the KDE Visial Guide conventions. A small list of grammar standards would be nice as well: text on buttons, click the button (not click in the button) (or maybe press the button?), buttons on the toolbars, text on the menu, text in the edit box? I don't feel comfortable to write this, since I am not a native english speaker. Rationale: a guide like this in a invaluable tool to documenters, especially the ones (like me) who are not native english speakers. - Refrain from using too much html formating in the whatsthis. Use bold, italic, and lists only when necessary, don't use the other formation options. Rationale: currently, KDE whatsthis look inconsistent in terms of text format. If one standars id to be selected, less formating looks good, and is more used (a lot of whatsthis text in code do not use formats), requiring less work to adjust existing whatsthis to the standard. - Do not use a title (such as "Save as button:") and then the real whatsthis text. It is redundant, as the widget is visible to the user. Things I want to discuss with you: - There are several ways to write whatsthis, I think we should recommend one. Here is the list of the ones I have seen (it is possible that even more forms exist): 1) The "action here" type: click here, select here, enter here. Example: "Click here to edit the item selected in the list box above." 2) The "action widget" type: click this button, select in this list, enter in this edit box. Example: "Click this button to edit the item selected in the list box above." 3) The "hidden subject type": "Edits the item in selected the list box above." 4) The "free text" type: "The list box above contains a list of items. By selecting an item and clicking the "Change..." button, you can edit it." 5) The "You can whatever" type: "You can edit the item setected in the list above by clicking this button." As you can see, it is a mess. Question: There should be a preffered form? if yes, which one? Should we direct the qwhatsthis coordination to kde-doc-english, as we do with the handbooks? qwhatsthis, as it stands today, is a kind of lost child... Cheers, Carlos Woelz -- Carlos Leonhard Woelz carloswoelz at imap-mail.com
