How-To / Procedures Guide¶
Title¶
Summary¶
Given, <YOUR_PROBLEM_CONTEXT_AND_INPUTS_HERE>, when, <EVENT_OCCURS>, then, by following this document’s procedures, <EXPECTED_OUTCOME_AND_OUTPUTS>.
Links¶
External¶
See the following resources for guidance on writing how-to guides / working procedures:
Wiki-How on clear instructions.
Wiki-How on general instructions.
The key to writing good documentation, from a technical writer and programmer.
Internal¶
Are there issue reports detailing one or more incidents that lead to this procedures creation?
Is there an architecture decision record detailing why this procedure was created?
Are there links to previously issued tasks upon which this procedure is based?
Prerequisites¶
What prerequisites are needed to successfully complete this guide’s instructions?
Tools:
<NEEDED_TOOL_1>
<NEEDED_TOOL_2>
Circumstances:
<NEEDED_CIRCUMSTANCE_1>
<NEEDED_CIRCUMSTANCE_2>
Warnings ¶
Is there anything to absolutely should not do?
Is there anything to be wary of?
Instructions¶
When creating instructions, limit your number of sub-tasks to a maximum of 5. Humans have a hard time remembering or holding in memory many more concepts than this.
Likewise, limit your number of steps per sub-task to a maximum of 6. If each step took one minute, then combined with 5 tasks, you’d have, at maximum, a 30 minute procedure. This seems as good a time to stop as any other arbitrary cutoff.
Sub-task 1¶
<YOUR_STEP_1>
verify: <THIS_STEPS_VERIFICATION_PROCESS_HERE>
avoid: <THIS_STEPS_FAILURE_INDICATORS_HERE>
estimated_duration_min: <THIS_STEPS_ESTIMATE_HERE>
<YOUR_STEP_2>
verify: <THIS_STEPS_VERIFICATION_PROCESS_HERE>
avoid: <THIS_STEPS_FAILURE_INDICATORS_HERE>
estimated_duration_min: <THIS_STEPS_ESTIMATE_HERE>
…
Sub-task 2 ¶
<YOUR_STEP_1>
verify: <THIS_STEPS_VERIFICATION_PROCESS_HERE>
avoid: <THIS_STEPS_FAILURE_INDICATORS_HERE>
estimated_duration_min: <THIS_STEPS_ESTIMATE_HERE>
<YOUR_STEP_2>
verify: <THIS_STEPS_VERIFICATION_PROCESS_HERE>
avoid: <THIS_STEPS_FAILURE_INDICATORS_HERE>
estimated_duration_min: <THIS_STEPS_ESTIMATE_HERE>
…
Sub-task 3 ¶
<YOUR_STEP_1>
verify: <THIS_STEPS_VERIFICATION_PROCESS_HERE>
avoid: <THIS_STEPS_FAILURE_INDICATORS_HERE>
estimated_duration_min: <THIS_STEPS_ESTIMATE_HERE>
<YOUR_STEP_2>
verify: <THIS_STEPS_VERIFICATION_PROCESS_HERE>
avoid: <THIS_STEPS_FAILURE_INDICATORS_HERE>
estimated_duration_min: <THIS_STEPS_ESTIMATE_HERE>
…
Sub-task 4 ¶
<YOUR_STEP_1>
verify: <THIS_STEPS_VERIFICATION_PROCESS_HERE>
avoid: <THIS_STEPS_FAILURE_INDICATORS_HERE>
estimated_duration_min: <THIS_STEPS_ESTIMATE_HERE>
<YOUR_STEP_2>
verify: <THIS_STEPS_VERIFICATION_PROCESS_HERE>
avoid: <THIS_STEPS_FAILURE_INDICATORS_HERE>
estimated_duration_min: <THIS_STEPS_ESTIMATE_HERE>
…
Sub-task 5 ¶
<YOUR_STEP_1>
verify: <THIS_STEPS_VERIFICATION_PROCESS_HERE>
avoid: <THIS_STEPS_FAILURE_INDICATORS_HERE>
estimated_duration_min: <THIS_STEPS_ESTIMATE_HERE>
<YOUR_STEP_2>
verify: <THIS_STEPS_VERIFICATION_PROCESS_HERE>
avoid: <THIS_STEPS_FAILURE_INDICATORS_HERE>
estimated_duration_min: <THIS_STEPS_ESTIMATE_HERE>
…