Guidelines for Writing Use Cases

The purpose of this document is to provide a short guide on writing "use cases" for the UIG. These use cases are essentially short how-tos devoted to particular topics of interest for users. These use cases should be short documents (less than five printed pages) that start with several introductory paragraphs (abstract, assumptions, etc.) and then the content.

Contributions should be a XHTML 1.1 file containing only the markup (tags) described below. Conforming to these guidelines helps the UIG maintain a common format and style for the use cases and helps with indexing and cross linking of documents. (See UsingXMLEditor for an editor that helps with the XHTML details.)

Use Case Title

The title of the use case should be enclosed in <h1> tags. The value used here will be used to generate the value for the <title> element and the header of the final pages.

Introductory Material

The introductory material is provided as a series of html paragraphs (<p> tags) identified with class attributes. The abstract is required. All others are optional, but should be provided if appropriate. Paragraphs should be closed with ending paragraph tags </p>.

1. Abstract (required): This section should contain a short summary of the goals of the use case and how those goals are achieved. It must consist of a single paragraph started with <p class="abstract"> tag.
2. Assumptions (optional): This section should describe the assumptions made by this use case or prerequisites which must be satisfied. It must consist of a single paragraph started with <p class="assumptions"> tag.
3. Related Documents (optional): This section should contain a list of links to related documents. It should be a single unordered list started with the <ul class="docs"> tag.
4. Grid Services/APIs (optional): This section should contain a list of the grid services or APIs used in this use case. It must be a single unordered list started with <ul class="gridservices"> tag.
5. Table of Contents: This will be autogenerated if the document uses <h2> or <h3> tags.

Content

The content should be a series of normal paragraphs started with the <p> tag. (Paragraphs should be closed with the end paragraph tag </p>.) The overall length of the printed use case should be no longer than around 5 pages (ideally shorter). The content may be divided into sections and subsections if desired. If the content has sections and subsections, then they must be delimited by <h2> and <h3> tags, respectively. Sub-subsections, etc. must not be used.

Inline Markup

It is often useful to identify particular words or phrases as commands, attributes, and the like. The following inline markup tags may be used in the use cases: <dfn>, <code>, <kbd>, <em>, and <strong>.

The <dfn> tag identifies grid-specific words or phrases that are defined in the text (or perhaps in an external glossary). An example is "Computing Element".

The <code> tag identifies words or phrases that are short code examples or attribute names. An example is "x = 10".

The <kbd> tag identifies words or phrases that are typed commands or options. An example is "edg-job-submit".

The <em>, and <strong> tags should be used to emphasize words or phrases. The <em> tag should be used for general emphasis; the <strong> should be reserved for warnings, traps, and the like.

Oftentimes in the command examples there are values that must be replaced by the user, for example, the user's Virtual Organization. The name of the such values should be prefixed with "my" if possible (e.g. "myVO").

Tables, Images, Links, and Lists

Tables, images, links and lists can be used when appropriate. The appropriate html tags should be used without specifying any style attributes. The style will be determined by the UIG stylesheet.

Preformed Text

Often in the use cases blocks of text are used to display program snippets, typed commands, and responses. All three of these should be indicated with the <pre> tags. Three classes are defined: "program", "response", and "command". A <pre> block with no class attribute will be treated as a "command" block.

Metadata

The <head> section of the document may contain the following metadata tags:

<meta name="Author" content=""/>
<meta name="ReviewDate" content=""/>
<meta name="Reviewer" content=""/>
<meta name="Id" content="$Id: AuthorTemplate.txt,v 1.7 2007/11/15 11:48:29 CharlesLoomis Exp $"/>
<meta name="keywords" content=""/>
<meta name="comment" content=""/>

Summary of Tags