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