Writing help for your app’s users

You‘ve created your great app and you want your users to be successful with it. This is where you come in - you can quickly create a rich text help page for your new app. This may sound like extra work but having help will save you time in the long run. Good help guidance is short by design, so this will not take as much time as you think. Writing up the basics of who should use the app, what the app is for, and a little detail about the app’s main workflow will help end users enormously. 

You can easily create a rich text help page for your help. Click here (https://help.quickbase.com/user-assistance/creating_a_document_page.html) for information about getting started with a rich text page. 

Your help should answer these questions: 

• What does this app do? 
• Who is it for? 
• Do I need special permissions? 
• How do I use it? 
• What do I do if something goes wrong? 

The best help includes just enough detail and no more. 

Research shows that most people can better digest short bits of information in groups of usually no more five items. With that in mind:  

• Avoid long words with three or more syllables. 
• Write short sentences, averaging 10 to 15 words. 
• Write help as though you were explaining your app to a coworker. 
• Use plain English rather than jargon. 

 As you can see, using a bullet list helps keep my sentences short and helps you take in the information. I’ve also used headings to break up the text visually and make information easier to find.   

Other things to avoid 

Work to avoid these: 

• Don’t use acronyms  - spell things out, especially the first time.  
• Don’t use different terms to mean the same thing – don’t make your reader wonder if Delete, Remove, and Erase are different things or the same. 
• Don’t write passive sentences  - Don’t say: “The house will be cleaned by you every Saturday.” Say: “You will clean the house every Saturday.” 

Let’s look at some examples 

In the same way, putting a procedure into a numbered step list makes it easier to follow and check off. Let’s look at two examples of procedures – which one would you like to follow? 

1. 1. Beat an egg, vanilla and cinnamon in shallow dish 
   2. Stir in milk, dip bread in egg mixture, turning to coat both sides evenly 
   3. Cook bread slices on lightly greased nonstick griddle or skillet on medium heat until browned on both sides 
   4. Serve with syrup.

The second version (which I’m guessing you picked) is easier to read for a few reasons: 

• It’s in step format. You follow each step and check them off. 
• It’s written in an active style – instead of “you will need to beat an egg,” I used “Beat an egg.” It’s direct and active. 
• I removed information that wasn’t absolutely necessary to complete the task – Instead of “To start making this yummy and easy French toast recipe you will need to…” I used a simple easy to find heading: “Easy French toast.” 

An app example 

 This is the ABC ltd Engineering Report app. Use it to: 

• Create new projects 
• Record project hours 
• Review project progress 

 This app is for engineers and senior engineers. You need have access privileges to use this app. Click here: (request access) to get started. 

How to use it 

1. Click on the new project button 
2. Enter information about your project. Your Employee and Team ID are required fields.  
3. Click on Submit when you are finished. Once submitted, other engineers and managers can see your report.

If anything goes wrong or you see an error, click here for help. 

Did our help achieve what we wanted? 

 Let’s review - did the help answer our questions? 

• What does this app do? 
• Who is it for? 
• Do I need special permissions? 
• How do I use it? 
• What do I do if something goes wrong? 

 Tools that help 

Here are some tools that can help you write better documentation. 

In your word processor 

Most word processors have built in spell and grammar checkers – use them to avoid embarrassing errors that make your document harder to read. 

Test how easy your text is to read 

Another great free tool to check your writing  

http://www.hemingwayapp.com/ 

This evaluates the grade level readability of your text. This doesn’t mean that you think your readers have a sixth-grade education, just that the lower the grade level, the easier it is to read for everyone. 

Peer review 

Ask a coworker to read your help and then try to use your app. Where did they get stuck? Did they have questions that weren’t answered? 

Good Luck! 

Keep it short, use plain English, answer the basic questions for your user, and take advantage of rich text features like headings, bulleted and numbered lists, and use tools and peers to check your work.