Macro documentation template

Owned by Vernica Downey
Last updated: Mar 11, 2013Version comment

How to use this template

This template is a modified version of the Aleph Macro Working Group (AMWG) macro documentation template. The "About this macro" section provides at-a-glance information for macro users and the "Technical information" section records in-depth information.

To create a new wiki page with this template:

  1. Click "Tools", then "Copy".
  2. Change the page name from "Copy of Macro Documentation Template" to the name of the macro being documented.
  3. Replace all text in angle brackets with the appropriate text, leaving unused sections blank
  4. Delete this tip box.
  5. Save the page.

Alternatively, macro developers can fill out the  Word version of this template (also available on the shared drive: H:\HOUGHTON\Technical Services\Shared\Macros\Documentation\MacroDocumentationTemplate.doc) and email the completed form to Houghton's MEXpert.

About this macro

Activation: <hotkey combination or other activation method>

Application: <e.g., Aleph, Oxygen>

Launch From:  <starting point for macro, e.g., Aleph holdings record or cursor in 245 field>

What this macro does

<Brief description of the macro>

How to use this macro

<Basic instructions for users>

Troubleshooting

<Tips for resolving known problems and dealing with errors>

Technical information

Name

<macro name>

Purpose

This macro <brief description of the purpose of the macro>

Activation

<hotkey combination, e.g., <Win>z, or other activation method, e.g., scheduled to run at startup>

Starting point

Start this macro in <exact location (e.g., application, window, pane, tab, field, or cursor point)>

Ending point

This macro ends <last step taken by the macro and any actions that the user must do next>

Assumptions

This macro assumes that:

  • <list of any conditions necessary for the macro to run properly>
Actions

This macro: <description of the steps taken by the macro; should be concise but detailed enough for user to identify where a problem may be occurring>

  1. <step 1>
  2. <step 2>
Submacros

This macro runs the following macros as subroutines:

  • <list of macros that the macro runs, both directly and through other macros>
Required shortcuts or key commands

This macro relies on the following shortcuts or key commands:

  • <list any key commands required by the macro, particularly any that are known to fail from time to time, such as the Aleph shortcuts for copying and pasting>
Files accessed

This macro uses the following files:

  • <list of files–with full file path–used by the macro>
Files created

This macro creates the following files:

  • <list of files–with full file path–created by the macro>
Variables Used

This macro uses the following variables:

  • <list of variables, formatted as "variable name": "description", e.g., T50: Aleph number or N2: Century>
Known issues/troubleshooting
  • <list any known problems and solutions to these problems, if available>
Additional information

<Any other useful information, especially for first-time users>

Development history

Created: <YYYY-MM-DD> by <developer's name>

Created in and for Macro Express <version number>

Created for <application with version number, e.g., Aleph 20.01>

Last revised: <YYYY-MM-DD>

Revision history

<YYYY-MM-DD> / <reviser's initials> / <description of changes made to macro>