Pathworks Procedure Authoring Standards (v1.3)
1. Procedure/Category Naming:
1.1 There are two types of procedures in Pathworks--those related to
services (whether internally or externally provided), and those
related to the internal working of the groups. Those in the
former category are categorized under
group/<group-name>/<proc-name>, those in the latter category are
categorized under service/<service-name>/<proc-name>.
1.2 Use spaces in procedure names to make searching easier.
1.3 Avoid words like "Procedure" "Process" and "Steps" in the name of
the procedure.
1.4 Always include the functional system in the procedure name (i.e.
"Reboot AMCOM Servers") even though it will appear in the category
name. This will make searching for procedures easier.
1.5 Use group names and categories already established within Pathworks
wherever possible. Categories will be added by the application
administrator as needed.
1.6 Names of procedures should indicate the goal or actions contained in
the procedure (i.e. Restart httpd on www.stanford.edu, Reboot the
AMCOM servers). Wherever possible, they should involve
active-voice verbs.
1.7 Don't use abbreviations in procedure names unless they are defined
in the "commonly defined terms" document.
2. Description:
2.1 Description should reiterate the functional groups who generally
perform the procedure and the goal of the procedure.
2.2 End state of the procedure should be spelled out in some detail
2.3 All affected systems should be listed.
3. Prerequisites:
3.1 What software do you need to have installed and/or running?
3.2 What system privileges do you need on any system you will touch
as part of this procedure?
3.3 What other procedures are prequisites (either one-time or every-time)
for this procedure?
3.4 What buildings or access-controlled doors do you need to finish
this procedure?
4. Steps:
4.1 Use commonly defined terms to describe elements in a procedure
***DOCUMENT TO BE WRITTEN (per functional group?)***
4.2 Images:
4.2.1 Use images where they are needed to describe a crucial step.
4.2.2 Don't do a screen capture for every step.
4.2.3 Always crop images to only display the necessary portions of
the screen.
4.2.4 Use the "Resize After" mode to insert most images. Having an
expandable "icon" of an image will
4.2.5 Make use of Circles/Arrows/Text on captured images to highlight.
4.3 External References
4.3.1 Procedure References in required steps should only be used when
absolutely necessary (as an prerequisite procedure that must
be performed exactly every time). This forces the user to
click through each step of the referenced procedure.
4.3.2 Optional procedure callouts are preferred in most cases,
especially any sub-procedure (i.e. software install) that
isn't strictly necessary each time the parent procedure is run.
4.3.3 Embedded URL links should not be used to call to another
Pathworks procedure--use an Optional Procedure callout
instead. Embedded URL links should be used for any reference
webpage outside of Pathworks.
4.4 Be aware of the audience of the procedure (i.e. the functional group
that will be performing the steps). Do not assume expertise and/or
privileges that the staff are not likely to have. Check with
the relevant functional group manager if you are unsure.
4.5 Write steps as imperative, positive statements and use active voice
(i.e. Do this, do that). Only use negative statements when there
is no clear positive statement that expresses the same action.
4.6 Follow standard English grammar and spelling.
4.7 Use arabic numeral, rather than spelled out numbers.
4.8 Be concise.
4.9 Use bold type, italics, and other emphasis markings sparingly.
4.10 Substeps and Hierarchical Process Flow
4.10.1 Each step or sub-step should represent a discrete action
(command issued or action taken.
4.10.2 Each completed discrete action should result in a check-off.
4.10.3 Use of a hierarchical structure in steps is preferred. A step
should signify a task, sub-steps should signify the actions
needed to complete that task.
4.11 Conditional steps should use the following format: IF <condition>
WHEN {NOT} <condition> THEN <action> IF NOT <action>. Multiple
IF's can be ANDed together. All conditional terms should be in
bold type.
4.12 For physical location information, use building names (Forsythe
Hall), floor (2nd floor), room number (Forsythe 246), and rack
location if applicable. Do not use colloquial names (Abdi's
Area, Phil's Cube).
5. Vetting/Production Rollout of procedures
5.1 All procedures to be put into production need to be approved by both
the SME and the manager of the functional group. The functional
Group manager is responsible for ensuring that the information is
accurate and performing the actual push to production.
5.2 Manager of the functional Group and the application administrator
are responsible for enforcing these style guidelines.
5.3 Application administrator is responsible for creating new categories
for functional groups or topics. Authors are responsible for
fitting their procedure into existing categories or raising
concerns to the Application Administrator and relevant functional
group manager.
6. Comments on Procedures
6.1 Unless there is an error in a procedure that will have major
reprecussions within the next hour if followed exactly, make all
comments "Feedback to the Owner". These will be seen by all owners
of that procedure.
6.2 Reference the procedure and step in any correction comment.
6.3 Explain the effects of the mistake in the procedure in any correction
comment.
7. Maintenance of Procedures
7.1 All procedures must be reviewed by the author or relevant subject
matter expert every 3 months. The application administrator is
responsible for reminding SME's that their procedures are up for
review.
7.2 If a user finds a problem with the procedure, they are required to
send a comment to author explaining the problem. Authors are
required to evaluate the comment and reply to the commenter.
Last modified Monday, 29-May-2006 05:00:00 PM
