There are several versions for each type of popup, a simple version with a minimum number of parameters and one or more "expert" versions where you can pass lots of parameters to fine-tune many details.

Use the simplest version one whenever you can. It's normally the version that makes most sense for most cases.

If you use an expert version, try to stick to the default behaviour (i.e. the behaviour of the simple version) as closely as possible. Change only parameters you really need to change. In particular, only change the default button for very good reasons.

If there is a specialized simple version, use it whenever you can. For example, use Popup::Warning rather than Popup::AnyMessage with the same message if you want to display a warning. This way we can make sure all warnings look the same and make them easily recognizable as warnings.

Sense or nonsense of providing headlines for each popup is a cause for endless discussion - we've been through that. Sometimes headlines make sense, sometimes they don't.

As a general rule of thumb, don't provide a headline that is more or less the same as the message itself, i.e. don't

// Example how NOT to use popups:
//
// - The headline is redundant
//
// - The text is too verbose
//
// - The text contains a reference to "YaST2"
//   (the user shouldn't need to know what that is)
{
    import "Popup";

    boolean answer = Popup::YesNoHeadline( "Create Backup?", // superfluous headline
					   "Should YaST2 create a backup of the configuration files?" );
}

this is plainly redundant. This could be done much better like this:

// Improved version of ask_create_backup_bad.ycp:
//
// Note there is no superfluous headline any more,
// the text is concise, and there is no more reference
// to "YaST2" (a user shouldn't need to know what that is)
{
    import "Popup";

    boolean answer = Popup::YesNo( "Create a backup of the configuration files?" );
}

i.e. concise question, no lyrics around it, clear, plain and simple.

If you need to provide more background information to the users so they can understand what tragedy could befall their machine should they chose either alternative, a headline makes perfect sense for the more experienced user who gets to this kind of question quite frequently:

// Example when to use a headline:
//
// There is lengthy text that advanced users might have read several times
// before, so we give him a concise headline that identifies that dialog so he
// can keep on working without having to read everything again.
{
    import "Popup";

    string long_text =
	"Resizing the windows partition works well in most cases,\n"
	+ "but there are pathological cases where this might fail.\n"
	+ "\n"
	+ "You might lose all data on that disk. So please make sure\n"
	+ "you have an up-to-date backup of all relevant data\n"
	+ "for disaster recovery.\n"
	+ "\n"
	+ "If you are unsure, it might be a good idea to abort the installation\n"
	+ "right now and make a backup."
	;

    boolean answer = Popup::YesNoHeadline( "Resize Windows Partition?", long_text );
}

	Note
	This example might be a good candidate for ContinueCancel() - see below

If you use headlines, please use them to either

Please DON'T use headlines like Question etc. - that doesn't have any informative value, yet it forces the user to read this useless headline.

For all those reasons, most popups come in a generic version where you can pass a headline ("Headline" is included in the names of those) and a simple version for general usage.

There are predefined messages for commonly used texts for the dialogs. Use them when you use the expert version of a dialog - don't pass your own messages if you can avoid it! Not only makes this life easier for our translators (they need to translate stuff like Cancel over and over again), it also gives us a chance to provide consistent keyboard shortcuts throughout the entire program.

`OpenDialog(
            ...
            `HBox(
:-)               `PushButton( `id(`ok ), `opt(`default), Label::OKButton() ),
                  `PushButton( `id(`retry ), Label::RetryButton() ),
                  `PushButton( `id(`cancel), Label::CancelButton() )
                  )
           )

`OpenDialog(
            ...
            `HBox(
:-(               `PushButton( `id(`ok ), `opt(`default), _("&OK") ),
                  `PushButton( `id(`retry ), "&Retry"  ),
                  `PushButton( `id(`cancel), "&Cancel" )
                  )
           )

The first part of the name always is the message itself literally Retry, the suffix indicates the type Button to indicate whether or not it has a keyboard shortcut. Currently we have Label::xxxButton (with keyboard shortcut) and Label::xxxMsg (without shortcut).