[kde-doc-english] qwhatsthis guidelines

[Carlos Leonhard Woelz]

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