How-to guide

This guide is adapted from the The Good Docs Project’s how-to guide. Use this guide to complete each section of the how-to template.

Introduction

A how-to takes your users through a series of steps required to solve a specific problem. It shows them how to solve a real-world problem or complete a task using Koha, such as how to close a library.

Note

A task is an action that your users can do with Koha to accomplish a goal. Multiple tasks may be involved in achieving a goal.

A how-to clearly describes a set of sequential steps to accomplish a task. The how-to assumes that a user has a basic knowledge of Koha.

How-tos are often confused with tutorials. How-tos are task-oriented, while tutorials are learning-oriented. The differences between the two:

Tutorial

How-to

Learning-oriented: Helps beginners or expert users learn a new feature in a hands-on way.

Task-oriented: Helps an expert user accomplish a task or troubleshoot an issue.

Follows a carefully managed path from the start to the end.

Aims for a successful result and guides the user along the safest, surest way to the goal.

Eliminates any unexpected scenarios and provides users with a successful finish.

Alerts the user to the possibility of unexpected scenarios and guides how to deal with them.

Assumes that users do not have any practical knowledge and must explicitly state any tools, file configurations, conceptual details, and so on.

Assumes that users have practical knowledge.

Why do I need a how-to?

A how-to is often used to help advanced users perform a task correctly. It can:

  • Demonstrate Koha’s capabilities.

  • Guide your users to solve a real-world problem with Koha through an ordered series of steps.

  • Help answer specific questions that users may have.

  • Make users comfortable using Koha.

  • Improve the user experience, and help reduce costs by lowering the number of support requests.

New users can also benefit from a how-to, provided the how-to is well-written and states any prerequisite knowledge required to complete the task.

Before writing a how-to

Before starting working on a how-to, identify:

  • The main audience or use case for the how-to.

  • The different scenarios that users may encounter in the real world while completing a task. If this, then that. In the case of …, an alternative approach is to…

  • The surest and safest way to complete a task. By suggesting multiple ways to complete a task, you’re asking users to think through the different ways and choose. Save your users’ time and effort by eliminating the options.

  • The potential scenarios that a user may encounter while completing a task, and their corresponding solutions.

Best practices for writing a how-to

  • Address one logical goal (task) for each how-to. Try to avoid cases where only a subsection of the how-to is relevant to the user.

  • Prepare your users for the unexpected, alert the user to its possibility and provide guidance on how to deal with it. For example, include callouts such as a warning, caution, or note to communicate important information while completing a task.

  • Use conditional imperatives. If you want x, do y. To achieve w, do z.

  • Do not explain concepts.

  • Sometimes it’s helpful to occasionally provide links to supporting pieces of documentation for more information. Particularly, when the user might need supporting background or conceptual information and reference materials. However, avoid providing too many links within the how-to. Keep your users on a single page as much as possible and provide links to additional resources at the bottom of the page.

  • Avoid over-documenting multiple ways of achieving the same task. If there is more than one way to complete a given task, pick and document the most common or recommended method of completing the task. Additional methods should be omitted or mentioned by providing a link or reference document.

  • Always ensure that the steps provided in your how-to guide are technically accurate. Test your how-to instructions from start to finish so that you can uncover omitted steps, incorrect details, steps out of order, and information gaps that block users. If it’s not possible to test it yourself, have a developer, librarian or subject matter expert demonstrate the step to you and record the session, if possible.

  • Re-test instructions after every notable product release to ensure instructions are still accurate.

  • Lengthy how-tos can overwhelm users. Focus only on one task in your how-to and restrict to a maximum of 8-10 steps per task. If the task is too big and complex, break down the task into multiple logical sub-tasks with their own steps.

About the “Overview” section

Use this section to provide:

  • A clear description of the problem or task that the user can solve or complete.

  • When and why your user might want to perform the task. For example, in a guide for creating a pull request, you might tell users that pull requests are used to let others know about the changes you have pushed to a branch on a repository.

The how-to assumes that a user has a basic knowledge of Koha and knows what they want to achieve.

Some examples:

  • This guide explains how to create an issue in Bugzilla. You can create issues to track bugs, enhancements, and new features for Koha’s modules and tools.

  • This guide explains how to temporarily close a library. Temporarily closing a library may require making several changes in Koha, such as informing staff and patrons, updating notcies, and extending loan due dates.

About the “Before you begin” section

{This section is optional}

This section describes what your users need to know, or need to have before they attempt the how-to. By stating the requirements up front, you prevent your users from getting halfway through and discovering that they need to go and read other documentation before they can continue.

Use this section to communicate any prerequisites for this how-to, such as:

  • Familiarity with the Koha module or feature

  • Any information, software, or tools needed

  • Environments to set up and configure

  • Authentication and authorization information

  • Other guides or information to read

  • Links to procedures or information, or any useful pointers about how to get what they need.

For ease of understanding, consider grouping prerequisites into categories such as background knowledge and software prerequisites.

Optionally, provide cues that signal to a user that they’re probably in the wrong place and offer more suitable options. For example, If you are a Linux user, refer to {link to relevant Linux how-to guide}.

Examples:

Before you begin, ensure you have:

* A conceptual understanding of RESTful APIs.

Before you begin, ensure you have:

* API credentials for the v3.5 API.
* Access to the Postman application.
* (Optional) A development environment (IDE) that displays API responses formatted for readability.

About the “Steps” section

The steps section is where you describe what the user needs to do. Use an ordered list to document the how-to steps. The template organizes the steps this way:

{Task name}

{Optional: Provide a concise description of the purpose of this task. Only
include this if the purpose is not clear from the task title.}

1. {Write the action to take here. Start with a verb.}

   {Optional: Explanatory text}

   {Optional: Code sample or screenshot that helps your users complete this
   step}

   {Optional: Result}

   {Optional: If needed, you can add substeps below a primary step.}

An example step:

Create a pull request

Pull requests are used to inform others of changes you have pushed to a
branch in a repository. Once a pull request is opened, you can collaborate
with reviewers and make changes before merging into the base branch.

1. To create a pull request:

   1.1. Navigate to the main page of your repository.

   1.2. Under your repository name, click **Pull requests**. By default, all
   open pull requests are displayed.

If you’re including code samples in your steps, make sure they are also indented correctly:

  1. Set your Git username for your repository.

    You can change the name that is associated with your Git commits using the git config command.

    git config user.name "Dakota Everson"

Tips for writing steps

  • For task names, start with a bare infinitive also known as plain form or base form verbs. For example, “connect”, “set up”, or “build” and express the heading as a complete thought. Don’t use the -ing form of the verb because it is harder to translate. Instead of saying, “Connect”, you might say, “Connect to the VM instance”.

  • For each step, optionally provide some background information about the task so users know what they’re about to do and why. Continuing with the example, you might provide some best practices for creating memorable repository names.

  • Optionally, add a code sample or screenshot after the explanatory text, depending on the type of how-to you’re writing. Screenshots are a great way to show specific parts of the screen you are referring to in a step. Make sure your code samples work and are always up-to-date.

  • Remember to orient your users when walking them through each step. If they need to open a particular file or dialog box to complete the task, provide that information first.

  • Provide examples of sample output such as return data or a message so that the users can validate whether they performed the step correctly or not. For example, you might want to show what a valid and expected result looks like on entering a command into a CLI.

  • Use plain language and define any technical term next to it.

  • Only include one action in a step.

For additional tips on writing steps, see writing procedural steps.

About the “See also” section

It’s likely that when explaining a process with multiple tasks that you will mention other topics related to the current one, but not strictly required. This section is useful to provide your users with suggestions on further reading without interrupting the topic covered by the current document.

An example might be setting up an email client, which requires working credentials for an active email address. The reader need not know how to install and run their email server to acquire that access, although this is potentially useful. The link to documentation on running a local mail server could therefore be included in the “See also” section.

Additional resources

Explore other guides and templates from The Good Docs Project.