Drupal: Organize and Construct a Self-Help Guide
Use this self-help guide to prepare your content and construct a self-help guide in Drupal Enterprise.
Create and Manage a Self-Help Guide
Self-Help Guide Overview
A Self-Help Guide provides the context and step-by-step instructions needed to learn about and complete specific tasks. Users can either start from the beginning of a self-help guide and follow it to the end, or they can jump in at any point to find the help that is most needed at the moment.
A Self-Help Guide provides the context and step-by-step instructions needed to learn about and complete specific tasks. Users can either start from the beginning of a self-help guide and follow it to the end, or they can jump in at any point to find the help that is most needed at the moment.
A Self-Help Guide (SHG) can be laid out in one to three column format depending on the scope of the content.
Multi-Column Self-Help Guide
A multi-column self-help guide can be used to convey a robust understanding of a tool or a process. Multiple columns are also useful if content needs to be divided into related but separate categories.
Single-Column Self-Help Guide
A single-column self-help guide can be used to address a specific problem or a limited set of instructions.
Structure of Columns
The structure of a column resembles an outline: major categories, sub-categories and supporting resources being linked at the lowest level. Resource links can go to an article for further reading, a website, or to media files.
Displayed Content Inline in a Single-Column Self-Help Guide
An effective use of the single-column self-help guide is to display the step-by-step instructions inline instead of as a linked resource.
Organize the Content
An effective Self-Help Guide (SHG) makes it easy for users to find the information they need. To accomplish this, it is important to have a clearly define purpose as well as an understanding of who the audience is for the guide you are creating.
Define a Clear Purpose
A SHG is more likely to be easy to understand and use if those creating it can easily answer this question: Why is this SHG necessary?
A clearly defined answer to that question will promote a clear focus when writing the SHG. Consider these additional questions when determining the goal:
- What is the problem or concern to be answered in the SHG?
- Is the SHG meant to introduce new information or a new process?
- What indicators will show that the SHG is helpful?
Draft a clear purpose statement for your SHG based on the answers to these questions.
Know the Audience
Take time to develop a clear picture of who will use the SHG. Carefully consider these questions to help analyze your audience:
- Who is going to use this SHG? Students? Faculty? Staff?
- Will they be frequent users of the application or process?
- Do they have the background to understand most terms used in the SHG?
- How would you describe the expertise of the intended audience as it relates to the SHG topic?
- Based on levels of expertise, what information should be included? What should be omitted?
- Will the SHG will be used regularly, or is the topic such that the SHG will be used infrequently?
- Identify someone in the targeted audience who could provide feedback.
A successful SHG begins with a clearly defined audience along with a specific purpose.
After determining the audience and focus of the Self-Help Guide (SHG), assemble stakeholders for a Rapid Task Analysis (RTA): a time for stakeholders to begin generating and organizing the content of the self-help guide.
The RTA Process
The Rapid Task Analysis (RTA) methodology was developed by Conrad Gottfredson. It is a systematic approach to identifying job tasks and related concepts and organizing them into meaningful process. This process is very helpful in creating an effective organization for a self-help guide.
To begin the RTA, clearly communicate the intended goal and audience for the SHG. This information needs to be kept at the center of the RTA process at all times. The participants in the RTA then bring their collective experience and knowledge to brainstorm a list of tasks and information needed in the SHG.
After fleshing out the information needed in the SHG, begin to group the information into logical chunks. These chunks will allow the audience to quickly scan the SHG for the needed information. Determine the logical flow or order of these chunks based on how the audience is likely to use the SHG. Carefully consider your audience when creating your labels for these chunks.
Key RTA Concepts
- The difference between tasks, steps, and a process (2m 5s)
- What is a concept (2m 36s)
- Chunking (2m 4s)
- Labeling concepts and tasks (2m 38s)
Prepare for the RTA
Generate and organize a list of tasks
Identify key concepts
Creating a new knowledge base article may involve writing something completely from scratch or curating an existing resource.
If there is an existing resource, there is no need to recreate the content. Instead, create an article that provides a description, including context for the resource, and link(s) to the content.
Curating Content
Search for Existing Content
Before you create a new article, Search for Duplicate Knowledge to see if there are any existing resources that could fill the need.
For example, a vendor may have step-by-step instructions or videos that can be leveraged.
- Note: If you find resources that are accurate in general but not specific to the University, you can link to them but provide the necessary information that will allow University users to adapt the instructions. You can always link to a resource within the body of a longer article.
Curate the Content in a KB Article
If you find resources that serve your purpose, create an article that describes and links to the resource.
- Create a New Knowledge Base Article following standard practices.
- Provide context for the resource link in the body of the article.
- If needed, provide the information University users will need to adapt instructions.
- Link to the resource instead of copying the information from the resource.
Example
TDX Article Subject: Google Hangouts: Known Issues
There are a number of known issues and errors with Google Hangouts. They fall into three categories:
- Sending and receiving messages
- Browser and installation issues
- General known issues
Google has a support page dedicated to Fix problems with Hangouts.
Any content generated locally for your self-help guide (SHG), i.e. content that is not external to the University of Minnesota, needs to be housed in one central location for easy access to revise and update as needed. Drafting documents in Google Drive is a great way to begin the process of collaborating. Once the content is drafted, decide a central location from which to store the content.
Drupal offers several benefits for storing content, and since the SHG will be made in Drupal, this storage option is particularly useful. However, there are other options for content storage that may be a better fit for your content.
Options for Storing Your SHG Content
|
Google Drive |
ServiceNow Knowledge Base |
Drupal |
Edit-ability |
Those that have rights to the doc, can use the suggesting feature to mark up the doc, can edit directly, or can make comments linked to some aspect of the doc (e.g. a word, paragraph, or image).
|
Requires access rights to ServiceNow. Only one person at a time can edit an article. Requires extra care to produce clean html. |
Requires access rights to Drupal. Only one person at a time can edit an article. |
Collaboration |
Easy to share and collaborate with multiple users. You can grant edit, comment, or view rights to get feedback internal to the doc. |
Can provide an article link to collaborators but feedback would have to be collected on a person-to-person basis. Has a built-in feedback function. |
Can leave notes on content only seen by other collaborators. |
Version control/ (built in expiration date for reminders to review content and update) |
Can see revision history. No built in reminders. |
Can set expiration dates to prompt content review. No built-in version control. You can create a pdf of each iteration for posterity. |
Version control and tracking is available. Drupal is highly customizable. You may be able to add additional features like expiration dates, automatic reminders, etc. |
Ease of use (technical know-how) |
Most University staff already use this. |
Requires some training. |
Requires training. |
Other considerations |
Works well for drafting content. |
For best results, this requires a feed of your content or some other type of integration from ServiceNow into your Drupal site. Talk to your Drupal Administrator. |
Since the self-help guide lives in Drupal it may make sense to also store the content in Drupal. |
Here are some questions to help you determine which system may be best suited for your material:
- What feature(s) are the most important to you?
- Are there any technological constraints? (i.e. does anyone on your team know how to navigate the ServiceNow Knowledge Base?)
- How often do you anticipate needing to update the content?
- Is version control important to you?
For further explanations of these options and help in deciding what is best for your SHG, consider scheduling a consultation with a Technology Trainer, [email protected].
A template is helpful when creating the layout of your self-help guide. It is much easier to see how the chunks of information should be arranged in preparation for entry into Drupal. The Office of Information Technology (OIT) training team has developed a template that mirrors the layout of a three-column self-help guide.
The following link prompts you to make a copy of the template for your own use: Self-Help Guide Content Tracking Template
Turn on Self-Help Guides in Your Site
The Self-Help Guide module has been installed on the UMN Enterprise Drupal platform, so it is very easy to turn it on in your site.
If you do not yet have a Drupal site, you can request it by completing a request form at z.umn.edu/siterequest.
Note: These instructions assume that you have logged into your Drupal site and that you have administrative permissions in the site.
Turning On the Self-Help Guide Module
- Click Extend in the Administrator Toolbar.
- In the filter text box, find UMN Self Help Guides.
- Select the checkbox for UMN Self Help Guides to enable.
- Click Install.
Create a New Self-Help Guide
Previously in Drupal, to create a self-help guide you needed to create separate columns and add them to a self-help guide page. Using Drupal 8 (D8), you can create a self-help guide page that already contains columns.
Creating a Self-Help Guide Page
- With your cursor, hover over Content in the Administrator Toolbar.
- Hover over Add Content.
- Select Self-Help Guide Page.
- Enter the title for the Self-help Guide in the Title field.
- Enter a Description. The description displays in the upper left of the self-help guide below the title.
Adding Columns to Your Self-Help Guide Page
Add columns to your Self-Help Guide to separate content into logical topics. Users can use the Column titles to orient where they may find a topic they need. The Column Title field displays the title that will show up in the Self-Help Guide.
- Enter the title for the column in the Column Title field.
- Select Add Guide Column to add additional columns.
- Continue to Work with Main Guide Categories.
In Drupal, Columns in a self-help guide are made up of Main Guide Categories, Subcategories, and resource links. For more information on the structure of a self-help guide, see Understand the Structure.
Main Guide Categories divide your self-help guide column into logical subtopics.
Note: These instructions assume you have logged into your Drupal site and that you have permission to create content in the site.
Creating a New Main Guide Category
- Go to the Self-Help Guide Page you wish to edit. By default, you are in the Columns tab.
- Find the Column you wish to edit.
- If you have multiple categories already created in the column, select Collapse All to the right of Main Categories to simplify your view.
- If you have multiple categories already created in the column, select Collapse All to the right of Main Categories to simplify your view.
- Select Add Guide Category.
- Enter a title in the Category Title field.
- Save or Publish the page.
- Note: The options you see for saving and/or publishing the column depend on how your site is set up.
Reordering Main Guide Categories in a Column
- Click and hold the Move icon
next to the Guide Category you wish to reorder.
- Drag the Guide Category up or down to the place where you want it, then release the Move icon.
- Note: It is easier to move the category one place at a time until you get it to the desired spot in the column order.
- Save or Publish the page.
Deleting a Main Category in a column
If you choose to delete a Main Guide Category, you also delete all Subcategories and links associated with it.
- Select the three dots to the right of the Main Category you wish to delete and select Remove.
- Save or Publish the page.
- Note: The options you see for saving and/or publishing the column will depend on how your site is set up.
In Drupal, Self-Help Guide subcategories contain links to resources and provide specific information for your Main Guide categories.
Note: These instructions assume you have logged into your Drupal site and that you have permission to edit content in the site.
Creating a New Subcategory in a Main Guide Category
- Go to the Self-Help Guide Page you wish to edit.
- Scroll to the Main Category where you wish to add a subcategory.
- Select Add Guide Subcategory.
- If you have already created multiple subcategories, select Collapse All to the left of the Subcategories header to find the Add Guide Subcategory button more easily.
- Enter a title in the Subcategory Title field.
- (Optional) Select Add Description to add additional text for the Subcategory. Description text appears below the link in the Self-Help Guide.
- Continue to the Work With Links to Resources section of this Self-Help Guide.
- Save or Publish the page.
Reordering Subcategories
- Click and hold the Move icon
next to the Subcategory you wish to reorder.
- Drag the Subcategory up or down to the place where you want it, then release the Move icon.
- Note: You can only reorder a subcategory within the same main category.
- Save or Publish the page.
Deleting a Subcategory
When you delete a Subcategory, you also delete all links associated with it.
- Select the three dots to the right of the Subcategory you wish to delete and select Remove.
- Save or Publish the page.
In Drupal Enterprise use links to direct readers to content such as How-Tos, Comparison Pages, Good Practices, and other resources. Links may go to outside resources or resources from within the same site.
Note: These instructions assume you have logged into your Drupal site and that you have permissions to edit content in the site.
Adding a Link to a Resource on Another Website
You can add a link to a resource within the Self-Help guide by entering a URL.
- Go to the Self-Help Guide Page you wish to edit.
- Find the Subcategory you wish to add a link to.
- Select Add Guide Link.
- Enter the URL to the link in the URL field.
- Enter a link title in the Link text field.
- Select Read or Watch from the Read/Watch dropdown.
- Note: This field determines the icon that appears next to the link.
- (Optional) Select a Resource Type from the dropdown.
- (Optional) Write a short description of the link in the Link Notes field.
- Leave the box un-checked in front of Display full body text for internal links.
- Note: This feature is not available for links to resources on another website.
- Save or Publish the page.
- Note: The options you see for saving and/or publishing the column will depend on how your site is set up.
Adding a Link to a Resource on the Same Website as the Self-Help Guide
You can link to resources contained in the same site as your self-help guide using the resource's title or node.
- Go to the Self-Help Guide Page you wish to edit.
- Find the Subcategory you wish to add a link to.
- Select Add Guide Link.
- Enter a title for the link in the Link Text field.
- Start typing the title of the internal webpage or content and Drupal will generate a list of matching pages that you can pick from.
- Select Read or Watch from the Read/Watch dropdown.
- Note: This field determines the icon that appears next to the link.
- (Optional) Select a Resource Type from the dropdown.
- Note: If you are providing a number of links in a subcategory, it can be helpful to your users to have the links grouped in categories.
- (Optional) Write a short description of the link in the Link Notes field.
- Note: The description will display below the link.
- (Optional) Check the box next to Display full body text for internal link if you would like the text of the linked webpage to display inline in the self-help guide.
- Notes:
- An effective use of a single-column self-help guide is to display the step-by-step instructions inline instead of as a linked resource. Displaying content inline is only recommended for single-column self-help guides.
- Only links to pages in the same website as the Self-help Guide that are created using the General page content type can be displayed inline.
- In a subcategory where you have chosen to display inline content, no other links to resources can be displayed. Only the page displayed inline will be visible.
- Notes:
- Save or Publish the page.
Reordering Links in a Subcategory
- Click and hold the Move icon
next to the link you wish to reorder.
- Drag the link up or down to place the link where you want to place it.
- Note: You can only reorder a link within the same subcategory.
Deleting a Guide Link to a Resource
- Select the three dots to the right of the Subcategory you wish to delete and select Remove.
- Save or Publish the page.