4  Procedure article element

The objective is a succinct statement of what is to be the step outcome.

The objective tells what the scope of the step or substep is. It should be enough in the Compact viewing mode to remind a person familiar with the procedure what to physically do at that point. While it is a rich-text element, it should only include formatting or links if they provide information useful for the step.

If the step or substep has any notes, there will be a ≣︎ checkbox at the end of the line that can be used to expose them. However, the ◪︎ checkbox before it will need to be checked.

The action section is explicitly stating what physical actions are required to bring about the objective.

If the objective is seen as presenting the intent, the action is telling what to do in practice. This is where what to click on, or otherwise manipulate, is described in unambiguous detail. If there are multiple ways to fulfil the objects, a list can be used. If useful, use an image showing that part of a previously displayed image focussing on where the action will take place.

The first block of the action section should focus on the physical action to be taken. Extra blocks might be needed to qualify the situation or circumstances, but should not add further actions. If a step element is covering a situation that is that complex, perhaps consider a substeps element, or another procedure.

Subsequent blocks can include tables, which can contain information to be entered for each possible scenario. Diagrams and programs can provide context or visualisation of the relevant aspect of the subject.

Typically, actions will be written in second person and active voice as an imperative (command). This is so the performer knows that it is something they are required to do. While being in second person, the You pronoun that would normally be used to start such statements is automatically implied in procedures, so can be omitted.

The response section states what happens when the action is performed.

The response element is where the results of physical actions is presented, including images showing changes, or lists enumerating what has changed. The introduction for an image can point out what to look for as the significant change. If there are several changes, a list can follow the image, but many other complex elements can be used as well. This is the only place post-action images should appear, to be used as confirmation that the step has been successful, and as the basis for the next step.

The response section is optional, but should only be left out if the result is obvious from the performer's view. They should always be left clear about the full extent of what will happen as a result of their actions. The response should include what they see happens first, and what changes are not visible after. While procedures for physical non-processor-controlled equipment have actions that typically only produce immediate visible results, any system that uses computers will typically result in changes of state for virtual entities or even other physical objects.

The scope or extent of any changes should also be included. For example, a step describing how to change an aspect of a program's visual interface should indicate whether it will be only for the current session or forever until changed, or whether it will only apply to the performer or everyone.

Typically, responses will be written in third person and passive voice, indicating that the performer is now an observer of the results of their actions, and that there is nothing they can do until the next step.

Notes are extra information about the step, usually as an aid to learning.

In normal usage, the body of the procedure should be solely devoted to the performance of the task, so other information within steps should be avoided, preferably putting it into the preamble before the steps. However, within a learning situation, understanding the step is important, so extra information may be required to spur some thinking about what is going on in the step.

To facilitate this, a notes element may be inserted at the end of the action and response elements. These can contain between one and nine blocks, which includes most of the complex ones, allowing for quite detailed notes. If a step or substeps has notes within it, a ≣︎ checkbox will be at the end of the Objective's line, though the preceding ◪︎ will need to be checked before being able to view them.

This is the basic step, covering one self-contained item of a procedure.

While a step element can have only one action element and an optional response element, lists and other complex elements can be used within them to enumerate multiple actions or responses, though they all must be related to the scope set by the objective.

Simplified step that simply provides a link to another procedure.

In a step link, the whole objective is a link. It can also have Action and Response sections, but they are optional. These are useful for dropping from one operational or structural level to another, such as being used for the steps of an overview procedure, as in the Overall setup procedure.

Owning step for up to nine substeps.

Substeps are for when there is a need for several steps related to the one subtask that would otherwise clutter up the procedure. For example, for the Add a file procedure, step 2 is a substeps element for handling the multiple steps for selecting the file.

The only difference between a substep and a step is that a substep cannot be assigned any roles. Otherwise, they have exactly the same structure. A substeps element is created with no substeps, but needs at least two up to nine. If nine is not enough, instead use a step link to point to another procedure, though a step with a link under its action will do as well, depending upon how much explanation is needed.

There is no equivalent to the substeps element that can be used in place of a substep. A substep link or links in a substep must be used for that. A substep link is like a Step link, also without roles, and can be used wherever a substep can. A substep link is useful for dropping from one operational or structure level to another.

There is no exposed action element interface for this element as its text is a predefined introduction to the substeps.

A procedure has an introduction that is displayed before the first step.

The procedure introduction usually states the objective of the procedure, starting with To. It is like a step objective, but for the whole procedure. Like any introduction, it is setting the scope for what follows.

Roles are to indicate the intended performers of each step of a procedure.

There can be up to nine roles specified, though only one might be needed for a procedure. Any step may have one or more roles assigned to it, though if there is only one role, it applies to the whole procedure and it cannot be assigned to any steps. Substeps cannot be assigned roles, as they are all expected to be performed by the same role(s).

The suitable names for roles are dependent upon the level at which the procedure operates. For an inter-department procedure, the roles may be the department names. Within teams, one of the roles will likely be Team leader. For computing code, the roles might be class names. For any scenario, avoid using particular people's names, but use their title instead, as that bypasses the need to update procedures when there is a change of staff.

Roles are listed under the article navigation bar, with a solitary role using a sentence, but more than one using a list.

Procedures must be complete, in that every step of the process they are documenting has a corresponding step element.

An example of incomplete instructions is when viewing a series of origami pictures that seem to include only every third step, making it difficult to replicate. This type of lack of completeness can spell problems if applied to company procedures, as it requires inexperienced performers to guess what the intermediate steps are, possibly resulting in omitted but critical actions, or inappropriate actions taken instead. Either of these unintended outcomes may not be found out until it is too late to correct them, perhaps resulting in damage or loss of reputation.

For processes like building equipment, incompleteness can result in having parts left over, indicating that there will likely be some mechanical issues if actually used, perhaps resulting in injury. Nonetheless, correcting the situation will involve some disassembly, usually by someone more experienced, resulting in excess time and expense, plus using up someone's time that could be better used being productive elsewhere.

It can be tempting to design procedures as if they are to be the complete process at one level of an inter-entity interaction, but that may make it difficult to produce useful metrics.

If trying to measure the performance of one entity in an inter-entity procedure, the timing for the overall procedure may not produce relevant results because the entities may be operating in their own independent timing from each other, or the procedure may be abandoned by one of the entities leading to open-ended timing. Metrics like overall procedure timing and abandonment percentages will be of use to those responsible for the whole process, but not for the individual participating entities.

In dealing with other entities, the better stance is to separate the process into a procedure to cover producing what is required for the other entity, and another to handle the response from that entity. This decouples timing from a dependency upon the other entity and still produces worthwhile timing results even if the other entity abandons their end of the process. A periodic procedure could check on outstanding requests and indicate actions depending upon the delay involved. This separation makes it a lot easier to manage the internal responsibilities and measure their performance.

If wanting to gain metrics, add steps or substeps at the start and end of a procedure or substeps to capture times and record results.

The number of steps is important for situations like testing.

While procedures for software or hardware are typically for users of them, they may also used for testing those systems. For testing, a procedure fails if any step fails, requiring correction of the errors before any more testing on the module or subsystem can be undertaken. The number of steps is a balance between having enough steps to produce a testable result, and having too many that increases the likelihood of failure.

Having too many steps may mean that too much functionality is covered, so that when a test fails, the developers have too many places that the errors could have arisen, prolonging resolution. Testing is like climbing a mountain, where each effort needs to get to a stable position from which falling is unlikely. Being too ambitious may result in falling too far. Each successful test is a milestone in the successful working of the system, but importantly a point at which the system was functioning correctly, so not needing examination for causes of errors.

Typically, testing works best with 8 to 12 steps, as the first couple are for setup and the last for cleanup, leaving enough to actually complete the task. Some procedures, like logging in, may only be a few steps but may be used by many other procedures, making them the exception to the optimal testing step numbers.

Another consideration is that each test procedure has an overhead for creating, debugging, documentation and approval, whereas adding a step is incremental, and while the procedure still needs approval again, it does not involve the investment of time that justifying writing a new procedure does. Just do not increase the risk of increasing test failures by adding too many steps.

While all procedures and instruction could be in one site, it may be better for maintenance to break them up into subdomains.

A large company could have thousands of procedures, perhaps in multiple languages, which might slow down a single Smallsite Design site. However, these could be split up into separate subdomains for each department or team, allowing decentralised operational maintenance while keeping a consistent structure.

Step links and substep links can be external links to Smallsite Design sites in subdomains or other domains that might be hosted in other parts of the world where the domains might be using their country's top-level domain. They can also be used to link to other documentation or systems, such as operational instructions written by the makers of machinery used by the company. Of course, in these external interfacing situations, the automatic backlinks to calling procedures would not be available, though they can be added manually in the Response section of the last step of Smallsite Design procedures.