+1

Thanks correcting my spelling mistakes @ngraham !

Thanks for working on this! Makes sense to me on first read.

For the case of showing an example as placeholder text, there might be cases where there is no string that could be an obvious example or at least might not be in all languages/localizations.

So would you think that alternatively a description of the type would be okay as well? Looking at existing code ( https://lxr.kde.org/search?_filestring=&_string=setPlaceholderText ) there are quite some places which have a description of the format/type than having a dedicated example.
If you would agree, what would you propose as formatting (capitalization, example end) and grammar ("A city name", "Some city name", "City name")

Could you also list some counter examples where the usage of the placeholder text is abusing the purpose? E.g. for giving other hints like "Click on button for selecting folder..."? or "Research is done from 3 characters"?

Looking around, e.g. in the UI of Firefox, one can see an action used still "Search or enter address", or some "Enter a bug # or some search terms" on https://bugs.kde.org/. Same "Enter here xyz" also found in KDE software code. Might there be a chance users still need that?
Edit: or are this exceptions from this generic rules, and perhaps things are different between form-like UIs and some other types (whatever those types could be defined as)?

Shouldn't the screenshots show english text for consistency?

Looking around, e.g. in the UI of Firefox, one can see an action used still "Search or enter address", or some "Enter a bug # or some search terms" on https://bugs.kde.org/. Same "Enter here xyz" also found in KDE software code.
Might there be a chance users still need that?

I'm not sure I understand what you are getting at. To me these seem to be actions, and are therefor a valid use of placeholders. But should end with an ellipsis (...).

In D12879#262744, @fabianr wrote:

At least to me something like that makes no sense.
The placeholder just duplicate the labels in a more verbose way, but don't add any information.

Agreed, in case of pure repetition of the label this only adds boilerplate.
Something to list in a "Don't" section?

Looking around, e.g. in the UI of Firefox, one can see an action used still "Search or enter address", or some "Enter a bug # or some search terms" on https://bugs.kde.org/. Same "Enter here xyz" also found in KDE software code.
Might there be a chance users still need that?

I'm not sure I understand what you are getting at. To me these seem to be actions, and are therefor a valid use of placeholders. But should end with an ellipsis (...).

What I mean is:
existing placeholder texts use something like "Enter here foo", which just tells the user what type of content or in which format should be entered into the input field. It does not tell what then is done with the input given.

Where the proposed text has this for actions: "The action should be triggered when the users types. Don't require the user to hit a submit button or key."
So "Enter" would not really be a type of action as described here, right? But more a variant of "In this input field you enter some foo." info.

So my question to the guides written are:
a) Given an input field without a label, due to other UI constraints, and which does not trigger action after changing the input, but instead is only used to collect data for further explicit processing, should one use just an example or a description as placeholder (e.g. "Bug number or some search terms"), or use some imperative text version ("Enter bug number or some search terms")?

The question is mainly triggered due to the amount of existing placeholder texts in software (from KDE and others). Personally I would be fine with just pure example/format description, but perhaps all the existing samples have a reason why they are like they are.

b) Given an input field without a label, due to other UI constraints, and which does not trigger action (same as a)) ...
b1) can one use the text otherwise used for the label as the placeholder text, and if so, in which style? E.g. an input field for a city, how should one use "City" as placeholder?
b2) can one use both the text otherwise used for the label and the formatting example, and if so, in which style? E.g. an input field for a city, taking either name or postal code, how should one make use of the placeholder text to give that info to the user?

Could you provide an example screenshot?

I searched around digiKam for the placeholders listed here https://lxr.kde.org/search?_filestring=&_string=setPlaceholderText , because they are quit wordy, but they seem to just repeat the label more verbose.

In D12879#263365, @fabianr wrote:

Could you provide an example screenshot?

Falkon UI would come to mind first (which currently seems inspired by other browsers' UI) where the location url field in the toolbar as well as the search terms field in the app-internal start page are labelless -> https://www.falkon.org/images/screenshot.png

Otherwise currently not aware of existing examples, sorry (mainly remembered own UI design drafts where I tried to go labelless when in need for screen real estate or desire for less clutter, in case the label was rather redundant for guiding the user or used often enough input element where the purpose was clear in daily usage. But never implemented finally in KDE software, trying to follow established UI patterns there for consistency).

I changed the wording for the action labels. Now the Falkon adress- and searchbar should be covered.

Another use of placeholders I came across today (could not make a screenshot sadly):

the placeholder described the state of an non-required option ("No url selected") where "url" was "url to a folder", "url to an image to fetch" or similar.
Which made me remembre to have seen before similar uses like "(No label shown)", when one could show a label to something by entering some text, but if input kept empty no label element would be used in the result (e.g. a diagram).

Which seems similar to the option with spinbox input elements, where one can set a text for a "zero" state, where the actual "zero" value rather means to toggles something off (cmp. QAbstractSpinBox::specialValueText).

So placeholder related question to guidelines would be:
if there is an option for some input data, which could be toggled on/off and also get some specific value (number or text), should this be done by two separate control elements (e.g. checkbox and value input field), or is using just the input field where a certain input value reflects the toggled off state also good? If only in some cases, when?

So if using the empty text input as "zero" state indicator if fine in KDE software for some defined cases, what is the recommended style for the text to use in the placeholder?

I landed that patch for now, because I feel even, if it does not cover every use case, it is better then no page about it.
But we can of cause always amend and improve it!