Skip navigation



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, 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

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
  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

Stanford University Home Page