Process Engineer Toolkit > User's Guide > Working with Project Webs > Authoring Process Web Pages > Rational Unified Process Styleguide

Topics

The Rational Unified Process Styleguide describes the conventions to use when modifying the Rational Unified Process Web site.  You may also wish to use these guidelines, or a tailored version of these guidelines, for developing your project Web site.

This guide is organized in these subsections:

Cascading Style Sheets (Styles) Pictures
Theme Hotspot Pictures
Templates Using Colors
Title Banner Tables
Top References
Bullets Vertical White Space
Italics and Bold File naming
Chapter and Section Numbering Microsoft® Word Template
Examples Index Online

The style of a Web site is enforced by theme, style sheet, and templates all of which are covered in the following subsections, along with some additional style issues.

Use these guidelines to keep a uniform look throughout your documentation. If applying them in a given situation looks strange or confusing, skip the guideline and use common sense.

Cascading Style Sheets To top of page

Each page is linked to a Cascading Style Sheet. 

The style sheet for the Rational Unified Process is located at the top-level folder of the Rational Unified Process.  To link the style sheet file to a page, the following line must be included in the header, which is the section between <head> and </head>:

<link rel="stylesheet" href="../../rop.css" type="text/css">

The path given above assumes that rop.css is located in the Parent-Parent folder. Adjust according to your actual relative path.

The style sheet for the Rational Project Web Example is called project.css, and is in the css folder below the top level folder.  To link the style sheet file to a page, the same instruction apply as above, except that the relative path would be "../../css/project.css"

The Rational Unified Process templates have a link to the rop.css file already. In most cases Microsoft FrontPage® manages to figure out the relative path once you save the new file in your directory structure. If, for some reason, it doesn't work, edit the HTML code appropriately.

There is a potential for overlapping between the theme and the style sheet. However, the Rational Unified Process and the Rational Project Web Example do not use the Microsoft FrontPage® theme.

In the style sheet, there are so-called classes defined for different HTML markups. When a file linked to a style sheet is loaded in the FrontPage editor, the style list displays the classes from which  you can choose.

Updates to the style sheet are immediately reflected without any changes in the actual files. Sometimes the FrontPage editor does not register the change, however, a Web-browser will once you reload.

Information on syntax and other details for style sheets is found in Cascading Style Sheets.

Style Classes To top of page

Banner headings Heading 1.banner and Heading 2.banner
Puts a colored background under the text.
Example heading Heading 5 (H5)
This should say "Example:".
Example Indent using the "Increase indentation" button, next to the buttons for bulleted list and numbered list, or use Normal.example.
Picture text Normal.picturetext
Definition Normal.definition
Used for definitions of modeling concepts. Do not use the predefined Definition for this purpose.
Table heading Normal.tableheading
Give table headings a bolder appearance.
Table text Normal.tabletext
Adjusts text to the left in tables.
a,b,c lists Numbered List.alpha.
Note that the FrontPage editor doesn't show the alpha characters, however, you can see them in the preview pane and in a "real" Web browser.
Bullets and Numbers For bulleted and numbered lists, use the predefined Bulleted List and Numbered List.
Plus and Minus bullets Bulleted List.plus and Bulleted List.minus
Uses a plus or a minus sign for bullet.

Different Browser Support To top of page

Microsoft Internet Explorer 4.0 supports all the style sheet features used in the Rational Unified Process.

Netscape Navigator 4.04 and 4.05 show the following signs that indicate a lack of support:

  • Active link color
 Defaults to red instead of the specified electric blue.
  • Table indentations
 The margin-specifier is ignored. To work-around, set table width to 85% if it's wider than the text and center alignment.
  • Bullets
 No special bullets appear; that is, the specifier "list-style-image" is ignored, therefore regular bullets, and plus and minus bullets, do not show up. Default bullets are used.
  • Alphanumeric lists
 Lists with letters instead of numbers turn out as numbers. (Style Numbered List.alpha)
  • Blue banners
 The blue heading banners don't stretch all the way across, which is a cosmetic problem.

Theme To top of page

Rational Unified Process and Rational Project Web Example do not use the Microsoft FrontPage® theme.

A theme governs navigation buttons, bullets, background, link colors, font styles, and sizes for regular text, headings, and more. Here are some of the features and disadvantages:

  • One of the strengths with themes is that Microsoft® FrontPage® supports creating and laying out navigation buttons and page banners. This is done using the navigation view information. However, Rational Unified Process Web sites do not use this feature. Other features with themes can be implemented with cascading style sheets and, because we aren't using the navigation bar feature, we can rely entirely on style sheets. See Cascading Style Sheets above, under the heading Different Browser Support for some of the problems experienced with Netscape Navigator.
  • Bulleted lists composed with a theme in place are actually implemented using tables rather than the HTML unordered list tag <UL>. When migrating to Microsoft Word®, bulleted lists are converted to tables with images instead of bulleted lists. Another problem is that indenting text with style sheets does not work for bulleted lists.
  • Themes are proprietary to Microsoft and are not an adopted standard, whereas style sheets are a standard. Netscape Navigator and Microsoft Internet Explorer show different things in some instances; for example, table borders show in Navigator when the theme dictates they should be white, that is, invisible on a white background.
  • It's unclear how themes and style sheets work together.
  • Opening HTML pages with a theme causes some Microsoft Word installations to crash.
  • When updating a theme, as well as a shared border, all files are visited, which means that all files must be checked in and the baseline frozen every time this is done. Style sheet updates do not affect any other files.

If you are using a Microsoft FrontPage theme

A FrontPage theme can be edited using the Theme Designer, which can be installed from the FrontPage CD.

It takes quite some time to re-apply a theme to a site of this size, because every file is visited. This means that all files must be checked out when re-applying a theme.

Theme files are kept in the Themes folder of the FrontPage installation folder.

The sizes of the different buttons

To maintain compatibility with pre-defined themes, FrontPage dictates certain sizes for theme button images. If your buttons have other sizes, things will move around when you apply another theme. Although the current theme does not follow these guidelines, here are the required dimensions:

Global navigation 95 x 20 pixels
Horizontal and vertical navigation 140 x 60 pixels
Up, Home, Next, Previous 100 x 20
Banner 600 x 60

The actual image can be smaller than specified, but the bitmap needs to have the above dimensions.

Templates To top of page

When creating a new page in the Rational Unified Process, there are templates to get you started and help you stay with the style of the site. These templates need to be installed in the FrontPage Pages folder.

  • FrontPage 98 users must follow the instructions from Toolkit: Installing FrontPage Templates to copy the RUP FrontPage Templates into the Pages folder of your FrontPage installation folder; for example,
    C:/Program Files/Microsoft FrontPage/pages. The Rational Unified Process template folders should end with .tem and be at the same level as the other template folders. FrontPage 2000 users can skip this step.
  • In the FrontPage editor, choose File->New.
  • From the list of templates, select the one you want. The Rational Unified Process templates are named "RUP xxx".

See Toolkit: Basic Authoring of Process Web Pages for more details.

Top To top of page

In order to quickly return to the top of a web page, place a top bookmark there and, after each major heading, add the top-arrow with a link to the top.

  • If there are top-arrows with links to the top, the easiest way to add another is to Copy, then Paste it.
  • If not, here is the procedure:
    1. Place the cursor before the title.
    2. Choose Edit->Bookmark... and write "Top" in the name field. 
    3. Check to make sure it isn't already included in the list. If it is, make sure it's placed before the title. Click OK.
    4. Copy this icon To top of page. Yes, we mean this icon right here.
    5. Paste the icon after the heading. Add a space between the icon and the heading text. Make sure the link to #Top was copied correctly too by moving the mouse over the icon and checking the status bar. It should say #Top.

Bullets To top of page

Be consistent using uppercase or lowercase letters, periods, and commas within a set of bullets. Use the style best suited for the information.

Use bullets to list an unordered series of items other than a sequence of events or steps.

Example: Full sentences

  • Begin each bullet with a capital letter.
  • End each bullet with a period, question mark or exclamation mark if it's a full sentence.
  • This is the preferred style and it's especially important for check points and longer bullets.

Example: A comma-separated list

    Use a comma-separated list where:

  • each bullet begins with a lower case letter,
  • ends with a comma,
  • it's the next to last bullet with either ", or", ", and" or something similar, and
  • the last bullet ends with a period, question mark, or exclamation mark.

Example: Simple list

When you have a list of concepts, names, and so on, begin each bullet with a lower case letter. Don't use any commas, periods or other punctuation. For example:

There are four different models in the Rational Unified process:

  • use-case model
  • design model
  • implementation model
  • test model

Numbered lists

Use numbered lists for ordered lists, such as a sequence of steps. Let each item be a full sentence.

Alpha lists

Use style Numbered List.alpha to create an ordered list with a, b, c, ... This type of list is used if you'll be referring to any of the items in other text; for example, see item a. above.

Italics and Bold To top of page

Use bold to emphasize. Do not use italics. Italic fonts are hard to read online and may not work correctly in all Web browsers.

Chapter and Section Numbering To top of page

Whether to number headings or not is still a debate. Customers have requested a way to easily and uniquely reference sections of the material. Because of the dynamic nature of hypertext, numbered headings are difficult to interpret because the headings may be displayed outside of the context of the numbered document. To avoid confusion, use unique names for section headings and fully qualify section references using the name of the page as well as the name of the subsection if it's ambiguous.

Where you must number, such as in brief outlines for documents, use the following convention:

1 Heading level 1 (three spaces between the number and the heading title)

1.1 Heading level 2

1.1.1 Heading level 3

Heading level 4 - 6 (no numbering)

Heading levels deeper than 6 are not used.

An appendix is named using letters: Appendix A, Appendix B, Appendix C, and so on.

Examples To top of page

Normal.example

Examples described separately from the body text should have the Normal.example style. Of course things can be exemplified directly in the body text as well.

Every text with the Normal.example style should be preceded by a line with the text "Example:" as a Heading 5 (H5).

Title Banner To top of page

In the Rational Unified Process, we do not use the FrontPage component for page banners. One reason is that they require updating in the Navigation View, which is a central file. Another reason is that we do not need the Navigation View for anything else, such as navigation bars, and it leaves one less thing to worry about.

What do we use? There are two styles in the style sheet for the top title:

Heading 1.banner

and

Heading 1.banner is used in major discipline chapters and other big titles having few words. Heading 2.banner is used for all objects in the process, because these usually have long names; for example, Activity, Role, Guideline. The templates show when they are used.

Unfortunately Netscape Navigator® and Microsoft Internet Explorer® treat background color for text differently. Internet Explorer colors the entire line from margin to margin, whereas Navigator only colors the area occupied by the text.

Banners, Navigation View, and HTML tag <title>

If you use the Navigation View and the FrontPage component for the banner, this might be good to know:

  • If the page exists and you drop it into the Navigation view, it will get the title, as specified, with the HTML tag <title>. This is just a copy and there is no magical relationship between these two titles. Updating the page name in the Navigation View will not update the title in the <title> tag. Changing the page title will not update the banner either, unless you remove the file from the Navigation view and add it again, but it's just as easy to edit the name.

Pictures To top of page

  • Pictures and tables are centered in the text column.
  • Pictures in tables are left-adjusted or centered.
  • Do not use frames around the pictures. With hyperlinked pictures, set border width to zero in Image properties.
  • Keep pictures small. The maximum width for a picture is 12 cm.
  • Download all pictures in CorelDraw format from the RUP Resource Center.

Printed documentation

For pictures that go into printed documentation as well as online, do not use bitmaps. The exception to this rule is screen dumps. CorelDraw is used to draw the diagrams in the Rational Unified Process, which are exported from the CorelDraw format to the GIF-format.

When creating printed documentation, the original CorelDraw picture is inserted into the proper chapter in Microsoft Word.

Some pictures are smaller than the minimum size CorelDraw allows for exporting to GIF. These may need a CorelDraw version, as well as a separately made bitmap version. See the section titled "CorelDraw tips" for more information..

Small images for online only

Icons, bullets, buttons, and so forth used only for online documentation can be created with a bitmap paint tool such as Image Composer, which comes with FrontPage, or CorelPaint. Adobe PhotoShop is also a current favorite. All of these tools require some experimentation to become familiar with them. Export pictures as GIF files. CorelDraw has a minimum size for exporting GIF files and, if it's not small enough, you have to scale the picture, which usually gives an ugly result.

If icons are to be included in the printed version too, you'll need corresponding CorelDraw icons for them.

CorelDraw tips

This is not meant to replace the CorelDraw manual, but solely to share experience.

  • Reuse similar pictures when creating new ones.
  • Bezier curves and lines can be copied and pasted, then easily reformed. You get the same line thickness and type of arrow head. Experiment with Bezier curves as they're easy and fun to use once you get the hang of them. Double clicking on a node to open a tool box allows you to remove and add new nodes.
  • You'll want to group icons with their text to create easy-to-move picture elements. Remember to adjust icon and text; for example, center text under roles and activities. Reusing groups for icons and text will preserve the distance between the icon and the text, creating a uniform look to the whole picture.
  • The font style and size for text under all icons should be in Arial bold 10pt.
  • If you round the corners of rectangles, out-of-proportion scaling will also change the roundness of the corners. It is better to draw the rectangle in the approximate proportions you want it before rounding the corners; for example, swim-lanes in workflow diagrams.
  • Adjust and distribute the picture elements to each other when you're done to avoid time-consuming, unnecessary adjusting.

Exporting to GIF from CorelDraw

To export a picture to GIF, follow this procedure:

  1. Select the entire picture. It's a good idea to group it.
  2. From the right mouse button menu or File menu, choose export.
  3. In the displayed dialog box, name the GIF file. Type the extension .gif with lowercase letters to make sure you get lowercase letters because UNIX servers are very picky with case and it's important to keep it uniform. Check the box for exporting only the selection.
  4. On the next dialogue that displays, specify:
    • Color: Paletted (8 bit)
    • Size: one-to-one
    • Resolution: 75 dpi
  5. In the final dialogue that displays, specify:
    • 89a-format
    • Check interlaced if you want; the picture loads with stepwise finer resolution
    • If relevant, choose a transparent color. This is usually white, index 215 in the default palette

Reusing pictures in many places

You can reuse a picture, even hotspot pictures, by placing them in an HTML-file by themselves then include them where you want them. This is useful for pictures that appear in more than one place.

  1. Choose Insert->FrontPage Component....
  2. Select Include Page.
  3. Specify the URL.
  4. Click OK.

Hotspot Pictures To top of page

It's very easy to create hotspots in pictures in FrontPage.

  1. Select the picture you want hot spots in and a picture toolbar appears.
  2. Mark the hotspots with the hotspot area tools, which are to the left in the toolbar.
  3. The displayed dialog asks for the URL to which you want to link the hotspot. You can double-click on hotspot areas to edit them.
  4. Once you deselect the picture, the hotspot frames become invisible.

Using Colors To top of page

First of all, colors take up lots of space—think twice before using them!

Web browsers use 216 colors from what is known as the color cube. Using the RGB scheme, the 216 colors are made up from a triplet of {00, 51, 102, 153, 204, 255): in hex that is {00, 33, 66, 99, cc, ff}. These ones are already in CorelDraw's standard palette.

We use a subset of these colors to keep the online version harmonious from a color standpoint. In the picture below, you can see the colors in our subset, and how they're used. As you may notice, we aren't using all of them yet. The names of the colors are shown to help you choose the right ones in CorelDraw. The RGB value is also indicated.

There is a custom palette, with the colors below as well as black and white, that you can use as follows:

  1. Download the palette file rup_palette.cpl. You might want to save it in the Corel installation folder, where the pre-defined palette files reside. In Corel8, it's in the Custom folder.
  2. In CorelDraw, right-click the Color Palette's border, then click Open.
  3. Choose the drive where the template is stored from the Look In list box. Color palettes have the extension .CPL.
  4. Double-click the folder where the file is stored.
  5. Double-click the palette's file name.

Tables To top of page

For headings in tables, use the style Normal.tableheading.

The theme rules that there should be no borders around tables. In fact, they are there, but they're white. If you really want visible borders, override with local settings.

Table placement

  • Tables are centered in the text column.

Text alignment in cells

  • Vertical alignment should be Top.
  • Horizontal alignment should be Default.

References To top of page

A "thing" is a role, artifact, guideline, activity, and so on. A "thing page" is a page with an activity, role, artifact, guideline, and so forth.

Kind of references

Examples

Comment
To a 'thing page' See Activity: Find Use Cases and Actors. Alt 1: In the text.
See Guideline: Use Case. Alt 2: In parenthesis.
To a section in a 'thing page' See the section titled "Timing" in Artifact: Software-Architecture Document. Hyperlink to a page. The user is supposed to find the section.
Hyperlink references to a chapter in a manual. See the section titled Overview in "Rational Unified Process—An Introduction". The manual within quotation marks.
Non-hyperlink references. See the section titled "Overview" in "Rational Unified Process—An Introduction". The section within quotation marks, the manual in quotation marks.
In-text reference (preferred alternative) Another technique is to perform role playing. See Role Playing, in which people act as business actors, business workers, and business entities. 
 
In-text reference
(second alternative)		 Another technique is to perform role playing, in which people act as business actors, business workers, and business entities. Warning: Avoid this style of reference.

General guidelines for cross-references are provided here:

  1. In the tables:
    Create hyperlink to the thing with no prefix, such as Use Case.
    Do not have the prefix, such as Artifact: Use Case.
  2. Do not mention the process when we reference as a "thing" in the process.
    Write 'see Activity: Use-Case Analysis'.
    Do not write 'see Rational Unified Process - Activity: Use-Case Analysis'.
  3. Avoid referencing a bookmark in another page. Use the style recommended above for references "To a section in a page". Of course, this requires that the named section ( called "Timing" in the example) is visible on the page. Otherwise you may consider a reference to a bookmark. There is also a problem that FrontPage doesn't support bookmarks very well.

Return and Shift-Return (Vertical White Space) To top of page

  • A return means make a new paragraph. In HTML you will get a <p>-tag or some other tag indicating a block of some sort. Usually, this is what you want.
  • A shift-return only inserts a new-line in the current paragraph, whereas in HTML a <BR>-tag is inserted. The shift-return is useful when:
    • a return gives you more vertical white space than you want; for example, an outline description
    • you want to control where the line breaks in a bulleted list or in any paragraph for that matter

File Naming To top of page

File names should be no more than 20 characters long and should contain only alphabets, numbers, and underscores (_). Spaces and most symbols such as &, *, ; should not be used. It is also highly recommended that all file names be named using lowercase letters.

The current file naming convention uses the abbreviations listed in the following table, and an abbreviated name of the file contents, separated by an underscore. For example, the artifact Use-Case Model is called ar_ucm.htm and the modeling guideline for the Use-Case Model is md_ucm.htm.

We are considering a different way to name files to accommodate the requirements of unambiguous page referencing. Customers have expressed a need to reference items in the process in an easier way and it makes sense to use the same numbering or code in the file name, or at least some sort of obvious mapping.

Concept Abbreviation
concept co_
activity ac_
role wk_
artifact ar_
report re_
discipline introduction int_
workflow detail wfs_
workflow graph wfsg_
iteration workflow iwf_
guidelines (for models, model elements, and artifacts) md_
work guidelines wg_
check lists ck_
manual pages im_
overview ovu_
examples ex_
Microsoft Word templates wd_
Rational SoDA templates so_
HTML templates wb_
guideline overviews mdov_
introduction manual im_
tool mentors tm_

Microsoft Word template To top of page

There is a Microsoft Word template for creating manuals in print called rup.dot. We suggest that you create a separate folder for Rational Unified Process Microsoft Word templates named, for example, "RUP" in Microsoft Word's template folder, which is typically C:\Program Files\Microsoft Office\Templates. Place a copy of this template file and others there. For more information on using Microsoft Word, see Toolkit: Basic Web Page Authoring to find out how to, and how not to, use Microsoft Word for HTML authoring.

Index Online To top of page

See Toolkit: Preparing for Publication for information on how to generate an index.

See the KeyWordIndex for more information on how to enter keywords into Rational Unified Process pages.

Copyright  © 1987 - 2001 Rational Software Corporation


Display Rational Unified Process using frames

Rational Unified Process