Sooner or later your application becomes so complex that you want to be helpful to the user.

One way of being helpful is to provide a help text that explains how to use the application.

Solution 1 : Use a dialog

Adding a help menu is easy, but the simple solution of showing a dialog with a little text is too limited.

	@Override
	public boolean onOptionsItemSelected(MenuItem item) {
		switch(item.getItemId()) {
		case R.id.menu_main_help:
			new AlertDialog.Builder(this)
				.setMessage(R.string.help_text)
				.setPositiveButton(R.string.ok, new DialogInterface.OnClickListener() {
					@Override
					public void onClick(DialogInterface dialog, int which) {
						dialog.dismiss();
					}
				})
				.show();
			break;
		}

		return true;
	}

This solution is simple to implement and can be translated easily by providing the same string in a translated resources file.

Here is the /values/strings.xml file for the default language (in this case english):

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="app_name">Example App</string>
    <string name="menu_help">Help</string>
    <string name="help_text">This is the help text. It should provide a simple explanation on how to use the application.</string>
</resources>

Here is the /values-de/strings.xml file for the german language:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="app_name">Beispiel App</string>
    <string name="menu_help">Hilfe</string>
    <string name="help_file">Dies ist der Hilfe Text. Er sollte auf einfache Art und Weise erklären wie man die Applikation benutzt.</string>
</resources>

The biggest disadantage is that it looks boring and that there is no easy way to add images.

Let’s find a better solution.

Solution 2 : Use a WebView with HTML file in assets

Maybe you already know about the WebView and think that this should give us a simple solution where you can have a nice looking help text containing images.

The question here is where to store the HTML content, so that it is easy to edit and can be loaded without hassle.

Some possibilities are:

• Hardcoded string in the Java code.
  • Pro: Easy to implement.
  • Con: Difficult to edit and translate.
• String managed by the resource manager (similar to the Dialog solution)
  • Pro: Easy to translate.
  • Pro: Separate from code.
  • Con: Difficult to edit.
  • Con: String resources can handle only simple HTML.
• HTML file on a Web server.
  • Pro: Can be updated independently from the application.
  • Con: Needs network connection to work.
  • Con: Difficult to translate.
  • Con: Somewhat difficult to manage.
• HTML file in the assets directory.
  • Pro: Easy to manage.
  • Con: Not obvious how to translate.

Let’s write an Activity that shows a hardcoded HTML file from the assets directory.

public class HtmlHelpActivity extends Activity {

	private WebView webView;

	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);

		webView = new WebView(this);
		setContentView(webView);

		// This simple but the help file cannot be translated, because assets are not managed language-aware by resource manager
		webView.loadUrl("file:///android_asset/help.html");
	}
}

This activity can be shown from a menu:

	@Override
	public boolean onOptionsItemSelected(MenuItem item) {
		switch(item.getItemId()) {
		case R.id.menu_main_help:
			startActivity(new Intent(this, HtmlHelpActivity.class));
			break;
		}

		return true;
	}

The biggest problem of this solution, is that the help file cannot easily be translated.
The assets directory is not managed by the resource manager in the same way as the values directory is.

But there is a simple solution by adding another level of indirection.

Solution 3 : WebView with localized HTML files

Instead of hardcoding the name of the help file, we use translated string resources to find a different help file for every language the application supports.

public class HtmlHelpActivity extends Activity {

	private WebView webView;

	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);

		webView = new WebView(this);
		setContentView(webView);

		// Use a translated string resource to store the language dependent name of the help file
		webView.loadUrl("file:///android_asset/" + getResources().getString(R.string.help_file));
	}
}

Here is the /values/strings.xml file for the default language (in this case english):

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="app_name">Example App</string>
    <string name="menu_help">Help</string>
    <string name="help_file">help.html</string>
</resources>

Here is the /values-de/strings.xml file for the german language:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="app_name">Beispiel App</string>
    <string name="menu_help">Hilfe</string>
    <string name="help_file">help-de.html</string>
</resources>

Now you can simply add as many help files as needed to the assets directory.