Document a Protocol

Last Updated: Oct 10, 2015 04:52PM PDT

Summary: As you write a protocol for executing via the Tasks app, you will need to provide documentation to assist users in knowing what your task does and how to run it. This documentation is provided by the standard help text fields of the top-level protocol.

The Summary help text of the protocol becomes the descriptive text under the task name on the task tile. This should be short enough to fit on the task tile, and not contain any HTML instructions. Its purpose is to allow the user to quickly understand what this task does before executing it.

The Description help text is shown at the top of the Task Settings dialog. There is room to provide a more detailed description, although authors are encouraged to keep the text brief (a few sentences will suffice). Again, it should not contain any HTML.

The parameter help of the protocol is displayed in light grey behind the type-in region of the task setting. There is only room for a few words, so use this sparingly. Typically, it is used to give a hint for a good default setting.

Look at a demo task protocol to see this in action. In your Pipeline Pilot Client, do the following:

  1. Open Protocols > Mobile > Demo > Fun > Where on Earth Am I.
  2. Right-click on the background and Edit Protocol.
  3. Go to the Help Text tab and look at the help text.

mob_document_protocol_interface.png

Next, you can check out how this looks in the Tasks app. (This example demonstrates using the protocol on an iPhone. On an iPad, the views will be slightly different.)

In Tasks:

  1. Activate your demo account (the account with Task Root set to "Protocols/Mobile/Demo").
  2. On the Home pane, open the Fun category.
  3. Scroll to the bottom to locate the tile for Where on Earth Am I. It should look something like this:

mob_fun_category.png

  1. Notice that the name of the task protocol is shown in bold, with the Summary help text displayed below it.

Next:

  1. Press Where on Earth Am I. The Task Settings are displayed and should look something like this:

mob_where_on_earth_am_i.png

  1. Notice that the name of the task protocol is shown in bold, with the Summary and Description help text displayed underneath. This allows the user to be presented with more information that could not fit onto the small area of the task tile.
  2. Finally, notice the light-grey text in the type-in region. This is the parameter help. There's not a lot of room, so you'll have to make your parameter help quite brief.

Tip: A good guideline to follow is to review the look of your help documentation by inspecting the task when it is seen in the Tasks app. This allows you to experience your task the way an end user would experience it.

Related

Tasks App (Creating New Tasks)

Tasks App (Tutorials)

Tasks App (Input Components)

Tasks App (Output Components)


http://assets1.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete