Writing Procedures Procedures provide users with a sequence of specific steps to realise a concrete outcome. End-users employ documented procedures when they are uncertain about how to obtain a specific system state. They typically search for relevant procedures based on the desired outcome. A complete procedure provides contextual information on its use case, describes an initial state, provides a sequence of steps, optionally describes significant intermediate states, and describes a final state.
The Four Parts of a Procedure Well-written procedures consist of four parts: 1. Introduction The Introduction, including the Procedure's title, provide the user with sufficient context to identify whether the procedure is the one that they are looking for. Many times users approach documentation with a specific problem that they need to solve, and they scan for something that matches their problem and offers a solution. The Introduction, including the title, should help readers to quickly make this determination. 2. Prerequisites The Prerequisites section lists the dependencies of the procedure. These are other procedures that must be performed before the steps of the procedure can be performed. For example, a configuration procedure usually requires that the product is installed. The prerequisites may be references or links to other documented procedures (for example: "Procedure 3.1: Install the product"), may be a description of the equivalent of a procedure result (for example: "A DNS entry mapping the hostname to the given IP has been created"), or may be a mixture of the two. Well-written prerequisites allow the procedure to function reliably in isolation, for example during documentation testing, or when a user jumps into the middle of a guide to solve an immediate problem. 3. Procedure Steps The Procedure Steps are the meat of the procedure. These are a sequential list of instructions that provide guidance to the user to perform the procedure and achieve the procedure outcome. Some of the steps may be optional, in which case the step should be marked as optional, and sufficient guidance provided to enable the user to make an informed decision about the optional step. Some steps may include a "Step Result", where the outcome of a step is described to illustrate feedback on the procedure pathway. 4. Procedure Result The Procedure Result describes the end result state of the procedure. This is especially important for testing. Given a situation that meets the prerequisites described in the procedure prerequisites, following the procedural pathway laid out in the Procedure Steps, the end result for a tester or an end-user should match the description of the Procedure Result.
Procedure-writing Guidelines Well-written procedures consist of four parts: Introduction Prerequisites Procedure Steps Procedure Result This section describes each of the four parts of a well-written procedure in more detail.
Procedure Title The procedure title is an imperative statement of the form "Do Something". As a user scans documentation for a solution they are often thinking "I want to...". A well-written procedure title matches that question, to allow the user to quickly locate it. Badly-written documentation does not use a standard pattern for procedure titles. Employing standard design patterns allows users to quickly learn the design patterns that have been used for the documentation, and then use those patterns to quickly assess the relevance of documentation without needing to read deeply in to the content. The following procedure titles employ a pattern that is better suited to a conceptual overview. Remember that users searching for procedural guidance usually approach the documentation with the question "I want to...". The example procedure titles below do not directly answer this question. Examples of badly-written procedure titles Fedora CD-ROM Install Mounting an NFS share Live USB key creation Well-written procedure titles follow the design pattern: Complete the question "I want to...". The example procedure titles below follow this pattern, and allow users scanning search results or a table of contents to quickly identify it as procedural guidance, and to assess its relevance to their situation. Examples of well-written procedure titles Install Fedora from CD-ROM Mount an NFS share Create a bootable live USB key
Introductory Paragraph The Introductory Paragraph provides additional context. When a reader locates a likely candidate procedure through search or browsing a table of contents, the Introductory Paragraph provides them with additional detail beyond the title. This additional detail may include further elaboration of the result produced by the procedure, a description of circumstances in which the procedure is appropriate, and links to other related procedures. After reading a well-written Introductory Paragraph a user is certain about whether or not this is the applicable procedure. In some cases the Introductory Paragraph may provide sufficient information to redirect the user to another similar but subtly different procedure which is a better match for their situation. The standard design pattern for the Introductory Paragraph is the following: "Follow this procedure to obtain specific outcome. To something similar but different refer to Other procedure. When procedures are authored as modular, reusable topics, rather than inline as static narrative, related and similar procedures are specified using the topic metadata, rather than written inline. The topic assembly system generates disambiguation references automatically.
Prerequisites The Prerequisites portion of a procedure presents the necessary preconditions for successful execution of the procedure. These preconditions must be satisfied before the procedure is started. A well-written procedure is sufficiently explicit in its dependencies that it can be executed or tested in isolation from the rest of the surrounding documentation. In the case of execution, users will frequently jump into documentation from a search or from a table of contents, attempting to solve an immediate problem. Well-written procedures do not assume that readers have read through and followed previous sections of the documentation. Procedures are tested as discrete, isolated units during Documentation QA in order to ensure this atomicity.
Procedure Steps Procedure steps are written using the imperative mood. This is the grammatical form used to give commands: "Do this...", "Press this key...", "Enter the following information...". The goal of user documentation is to reduce uncertainty. Once the user is certain that the they have the right procedure, each step then guides them through a pathway with the greatest amount of certainty as possible. Procedural steps do not attempt to educate the user on background conceptual information, but provide a set of concise steps to achieve a desired outcome. In a case where a procedure involves options, each option is presented with sufficient information for the user to make an informed decision. Remember that the goal of documentation is to reduce uncertainty. Presenting users with options devoid of sufficient context for them to choose increases their uncertainty. If the amount of contextual information required to make a decision in a procedural begins to overload the procedure with conceptual background, break it out of the procedure, and consider providing different procedures for each of the use cases, or breaking the procedure into a shared preliminary procedure with separate subsequent procedures for the different options.
Step Results Some procedure steps present a step result. A step result helps the user to verify that they have executed the step correctly and the system is responding in the manner predicted by the procedure writer. Without step results a user may not notice a deviation from the documented procedural pathway, due to either user error or an unexpected response by the system, until they have travelled several steps beyond the point of departure. Procedure step results are presented in the simple present tense. This is the grammatical form used to describe something concrete and immediately present: "The window appears...", "A new user is created...", "The command returns the following result...". Complex tenses, future tenses, and wording that is hypothetical or "hopeful" ("it will do this", "you should see this") inject uncertainty. Remember - the goal of documentation is to reduce uncertainty. Documentation that speaks with certainty creates certainty. Clear, confident step results mean that the user is certain they are on the right track as they follow the procedure, and when the user experiences a result contrary to the documented one, they are just as certain that things have gone awry.
Procedure Result The Procedure Result describes the end state of the system when the steps of the procedure have been performed correctly. This is a complete description of the procedure results, the goal of which is to leave no uncertainty about the extent and limit of the procedure's outcome.
Example Procedure An Example Procedure Add a new user with the graphical user management tools Follow this procedure to create a new user account on a Fedora system using the graphical user management tools. To create a new user with the command line tools, refer to Procedure 4.5 "Add a new user with the command line user management tools". Prerequisites Fedora installed and running Access to the root account, or root-level privileges via sudo Ensure that the User Manager application, system-config-users, is installed. In a terminal, run the command rpm -q system-config-users to query the installed packages database. Result: If the application is installed, the command returns the installed package version, for example: system-config-users-1.2.107-2.fc15.noarch If the application is not installed, the command returns: package system-config-users is not installed If the application is not installed, run the following command with root privileges: yum install -y system-config-users Result: The system-config-users package is installed. Start the User Manager application from the command line or via the Graphical User Interface (GUI). Command-line option: In a terminal, run the command system-config-users, or sudo system-config-users if you have sudo privilege. Result: If the command is run with root privileges, the User Manager application appears. If the command is run with non-root privileges, a root password dialog is displayed first. GUI option: In the Gnome Activities menu, type "Users" (without quotes). Select the application Users and Groups. Result: If you are logged in as root, the User Manager application appears. If you are logged with a non-root account, a root password dialog is displayed first. In the User Manager, click Add User. Result: The Add New User dialog appears. Specify the details for the new user. The following parameters are required: User Name, Password, Confirm Password. The following parameter is optional: Full Name. Note that when the "Create home directory" option is selected, a home directory is created at Home_Directory_Value/New_User_Name_Value. Click OK. Result: A new user is created, and displayed in the User Manager.