Rational Developer Network Content Style GuideDecember 3, 2002Significant additions and changes from the July 18, 2002 version are marked in green. About This GuideThis style guide for Rational Developer NetworkSM content supplements the following resources:
Some points made in these other references are repeated here for emphasis, but in general there isn't much overlap. If you don't see what you're looking for here (or you'd like more information), look there. In case of conflicting guidelines, the ones in this style guide take precedence, followed by the others in the order listed above. This guide currently allows for articles to be written either in Microsoft Word (or a similar word processing format) or directly in HTML, and some differences are noted accordingly. A Word article template is available that address issues not covered in this guide (for example, exactly which fonts to use). Finally, note that this guide follows the style it recommends and so can be used as a model (except for obvious differences due to the different type of content). In particular, note that italic is used for "words as words," but this doesn't mean (unless stated otherwise) that those terms should be italic when you use them. Style Guide EntriesAbbreviations (and Acronyms) — Strictly speaking, an abbreviation is the shortened form of a word, whereas an acronym is a pronounceable term formed from the initial letters of a phrase (such as ASCII); however, here we'll use abbreviation to cover both. In general, spell out the abbreviation first and then put it in parentheses. The Internet Engineering Task Force (IETF) is working on a new version of its specification governing Web bridges, routers, and dental work. For abbreviations that should be very familiar to the reader, this order can be reversed; that is, you can use the familiar abbreviation first and then parenthetically spell it out. Or don't spell it out at all if even that should be painfully obvious to the reader (or of little interest). For example, except perhaps in basic, primer-level documents, the following abbreviations don't need to be spelled out:
In the interest of preventing alphabet soup, minimize using abbreviations by substituting pronouns where doing so won't be too vague or otherwise confuse the reader. See also Slang. above — Rather than this, use earlier for references to a previous place in the article, unless you're referring to something immediately above (such as items in a preceding list). Abstracts of Articles — In writing abstracts that appear below article titles in Knowledge Centers, try to observe the preferred length limit of 200 characters, and always observe a 250-character maximum length. Acknowledgments — These can be made in a (first-level) section just before the bio, headed "Acknowledgments" and with contents like Many thanks to Firstname Lastname for his assistance in reviewing this article. or The author would like to thank Firstname Lastname for her assistance in preparing this article. add-in — Capitalize this term only if the add-in is identified as part of a product, as in the Patterns Add-In. Alphabetical Order — The following guidelines apply where alphabetical order has to be figured out by hand (such as in this style guide, as opposed to a program-generated index).
Apostrophe — The special apostrophe character (as opposed to a straight "single quote") is acceptable in a Word document, but don't bother entering the code for it in HTML. (It won't survive in the final article.) ASP.NET — No space (that is, not ASP .NET). ASP stands for Active Server Pages. Asset Articles — These guidelines apply to articles describing reusable software assets. Don't include the asset version (or release) number in the article title if new versions are expected to replace old versions. Include such a number only if the new and old versions are expected to coexist in the future. Like any Rational Developer Network article, an asset article can state the article authorship as simply "Rational Software." In this case, the asset author can be stated in the article's "Classification" section as either "Rational Software" or a person (or persons). Author Byline — In general, don't include the author's corporate affiliation in the byline. Stick to author names only, leaving further details to the bio at the end of the article. Exceptions:
Leave designations such as Dr. out of the byline (and bio). bean — Lowercase. See also Enterprise JavaBeans and JavaBeans. below — Rather than this, use later for references to a subsequent place in the article, unless you're referring to something immediately below (as in a sentence introducing a list). bolero.net, boleroXML — Initial lowercase; avoid placing at the beginning of a sentence. (Actually, bolero.net subscripts the XML in boleroXML, but we don't want to mess with that in HTML.) Bulleted Lists — See Lists. Captions — All figures (even within tutorial-type steps), tables, and long listings (more than just a few lines of code) should have captions. Capitalize only the first word of captions. Don't end the caption with a period (unless it's a sentence, which should be rare). Figure 1: Flow of exchange between documents catalog — Not catalogue. change management — Don't abbreviate this term to CM (which is the abbreviation for configuration management). click — You click something on the screen (like a button), you don't click on it. But you click in an area like the inside of a window. You don't click and drag; you just drag. The click action ends with releasing the mouse button, whereas a drag is done with the mouse button still down. client/server — Not client-server. CM — See configuration management (CM). Code Font — A special (typically monospaced) font is used for the following:
The following should not be in the code font:
Commas — Use serial commas (that is, when there's a series of three or more things). I asked my husband to go to the store to buy bread, milk, and eggs, but he bought Ho-Hos instead. Commands in Menus — See Menus. Companion Documents — Articles can link to other documents posted along with them, commonly referred to as companion documents. These might include, for example, a supporting case study or glossary, or an elaboration on a section referred to in the main article. The following guidelines assume that the companion document is referred to from the main article; it's also possible, although not advisable, for this to go down another level (that is, with a companion document linking to a companion of its own).
Company Names — In general, there's no need to spell out company names and locations in full. Exception: In a sidebar or a list of products/vendors intended to help readers find things, it's good to provide the full company name and location, particularly for smaller vendors that may be more difficult to find. comprise — This means to contain or to include, as in "The United States comprises 50 states"; however, since this isn't common usage, it's best to choose other wording, such as "The United States consists of 50 states," or "The United States is made up of 50 states." Especially don't use comprised of. Conclusion — Articles don't necessarily have to end by summing up everything covered, although a concluding section does prevent an article from ending too abruptly. Try to rephrase the dry section heading "Conclusion" (or "Summary") that commonly crops up at the end of the article to something with a jauntier, less formal tone. The reader will logically be expecting a wrap-up at the end, so the heading doesn't have to strongly convey the idea of conclusion. content management — Don't abbreviate this term to CM (which is the abbreviation for configuration management). Contractions — Use them liberally. Cross-References — In cross-references, use quotation marks around titles of articles and other documents that don't qualify as books, and around headings of sections within the same article. Don't refer to specific sections within other articles. See Links for information about how to set up cross-reference links, and References for how to list references at the end of an article. Dash — See Em Dash or En Dash. Dates — Use the U.S. format, "month dd, yyyy," always spelling out the month name. The W3C decided on January 20, 2000, that developers must now left-align all code. Include the day of the week if it's pertinent. Jughead's Codefest will be held on Monday, August 28, 2000. Don't use ordinal numbers to indicate a date — for example, not August 28th. development accelerators — Not e-development accelerators. The related initiative is now called the Rational Development Accelerators initiative (and the related Rational Developer Network center is the RDA Exchange). dialog — Not dialogue. double-click (v), double click (n) — Hyphenated when used as a verb but not when used as a noun. drag-and-drop (adj) — Note the hyphens. Don't use as a verb, and avoid using as a noun. dynamic link library (DLL) — Not hyphenated. Avoid the jargon dynalink. e.g. — Use for example instead, except perhaps in a table or figure for brevity. earlier — Use instead of above for references to a previous place in the article, unless you're referring to something immediately above (such as items in a preceding list). e-business — All lowercase, hyphenated. When necessary to capitalize it (such as at the beginning of a sentence), use e-Business. e-commerce — All lowercase, hyphenated. When necessary to capitalize it (such as at the beginning of a sentence), use e-Commerce. e-development accelerators — Use development accelerators instead. The related initiative is now called the Rational Development Accelerators initiative (and the related Rational Developer Network center is the RDA Exchange). Em Dash — Surround em dashes with spaces. Either type two hyphens for an em dash or type the special character for it, as follows:
The em dash character, unlike almost all other special characters, will survive in the final HTML format. e-mail — All lowercase, hyphenated. When necessary to capitalize it (such as at the beginning of a sentence), use e-Mail. e-Mail Addresses — In Word, select the text you want to hide the address behind, and insert the appropriate link using the Insert Hyperlink command (remembering to include the "mailto:"). In HTML, hide the e-mail address in a link. Dyan can be reached by e-mail. Emphasis — See Italic. En Dash — Where you would otherwise use an en dash, use a hyphen instead; en dashes are replaced by hyphens during conversion to HTML. See also Em Dash. Enterprise JavaBeans (EJB) — This word is a trademark; never use it in the singular, Enterprise JavaBean. EJB is a separate trademark, not just an abbreviation for Enterprise JavaBeans. The term enterprise bean is an alternative (often more convenient) way of referring to referring to an EJB component. Like all trademarks, Enterprise JavaBeans is best used as an adjective and not a noun, at least the first time or two. See also JavaBeans. etc. — Use and so forth or and so on instead, except perhaps in a table or figure for brevity. Exclamation Point — Use sparingly. Extensions in File Names — See File and Directory Names, File Extensions. extranet — Lowercase. Figures, Tables, Listings — Call out every figure, table, or listing by number in the paragraph preceding it, as Figure N, Table N, or Listing N (even if only enclosed in parentheses rather than worked into a sentence). In HTML, don't make this reference (or any similar one immediately following the figure or whatever) a link; however, if you refer back from a later section, do make that reference a link. Exception: When the item (typically a figure in this case) doesn't directly relate to the text but rather is a supplemental, optional adjunct to it (such as a humorous, cartoon-like illustration), there's no need to call it out. See also Captions and Table Heads. File and Directory Names, File Extensions — Put these in the code font. Unless the context requires otherwise (for example, in a reference to an actual file's extension that's all uppercase), use all lowercase for extensions. Assume that the period at the beginning of the extension will be pronounced "dot." The file name named DoThis.exe has a .exe extension. Navigate to HKEY_LOCAL_MACHINE\Software\RationalSoftware\ClearQuest\Email. firstly — Do not use; use first instead. First, consider the effect that Ho-Hos might have on your digestive system. Footnotes — Don't use them. See Notes and
References.
forward engineering (n), forward-engineer (v) —
Only the verb is hyphenated.
Function Names — See Routine, Function, or Method Names. functionality — Avoid overusing this word. Try features or capabilities, for example. grok, grokked, grokking — Note the double k. HTML Elements — This guideline concerns how to refer to HTML (or XML) elements in text. When the reference is specifically to a tag, it should be, for example, "the <p> tag." When the reference is to the element, do likewise, as in "the <p> element." Even though strictly speaking the element is more than just the tag, this terminology is common practice and unambiguous. It's also acceptable to use a term like paragraph element, but only if you've made crystal clear what the related tag or tags are. i.e. — Use that is instead. IIS — Short for Microsoft Internet Information Services. include — Avoid using before a list that's complete. For example, you'd say that the Three Stooges are Moe, Larry, and Curly, not that they include Moe, Larry, and Curly. input — Don't use as a verb. Try enter or type, for example. Internet — Always capitalized. intranet — Lowercase. Italic — Use italic for the following:
See also Quotation Marks. J2EE — Per Sun, this stands for Java 2 Platform, Enterprise Edition. Java Archive (JAR) file format — Refer to it as a JAR file for short (not just a JAR). JavaBeans — One word; note capitalization. This word is a trademark; never use it in the singular, JavaBean. The term Java bean (or bean for short) is an alternative (often more convenient) way of referring to a JavaBeans component. Like all trademarks, JavaBeans is best used as an adjective and not a noun, at least the first time or two. See also Enterprise JavaBeans. JavaServer Pages (JSP) — Not Java Server Pages. Refer to a JSP page (or JSP pages), not to a JSP (or JSPs). Knowledge Center — Always capitalized. Don't refer to a specific Knowledge Center (or any similar categorization) in articles; they change too often. later — Use instead of below for references to a subsequent place in the article, unless you're referring to something immediately below (as in a sentence introducing a list). left-hand, right-hand — Unless a reference to someone's actual hand, use just left or right. leverage — Avoid overusing this marketing jargon. lifecycle — One word. Links — See URLs and e-Mail Addresses for information on links to resources outside the article and on "mailto:" links. There can also be links to locations within the same article — for example, to a later section (if skipping directly to it is advisable) or to a list of references at the end of the article. Such links should be set up as follows:
Listings — See Figures, Tables, Listings. Lists — Use bulleted instead of numbered lists except when order is implied, as in the steps of a process. Use lists liberally; they often make an article more readable. A clue for when a list might be advisable is when numbers are expressed in the text, as in "There are three <whatevers>" followed by sentences describing each one, or as in a paragraph containing sentences that begin "First," "Second," and "Third." A list is especially preferable to a solid paragraph of text when successive sentences have the exact same structure; this can sound tedious in solid text but usually works very well in a list. Make the items in a list parallel -- for example, in whether they begin with a sentence fragment or a complete sentence. If the items aren't complete sentences, don't capitalize them or end them with a period (with one exception, below); otherwise, capitalize and punctuate them in the usual way for sentences. Don't end items in a list with any mid-sentence punctuation, such as a comma or semicolon, or end them with conjunctions such as and or or. Lists may be embedded within lists, one level down. In that case, the higher-level items should always be capitalized, even if not complete sentences.
If the listed items begin with heading-like text that you want to highlight in some way, use bold.
log in, log out — Not log on or log off. Use log in to, not log into. Use login or logout as the corresponding noun (or adjective). look and feel — Not hyphenated. Menus — Commands are chosen, not selected, from menus. An acceptable shorthand for showing commands within menus (except when addressing the most beginner-level audience) is, for example, Choose Settings > Executable Settings rather than From the Settings menu, choose Executable Settings. In fact, this notation can be extended to include tabs, buttons, and other user interface elements, as in the following: Settings > Executable Settings > PowerCheck tab > Modules button > Clear Cache button Where a command brings up a submenu, that submenu can be referred to as, for example, the Start > Programs menu. meta (prefix) — Don't hyphenate words beginning with meta (for example, metadata and metatags) except where necessary to avoid confusion. metadata — Capitalized when used in a proper name (such as the Metadata DTD) but lowercase in generic uses (as in import the metadata). Method Names — See Routine, Function, or Method Names. Microsoft .NET — Note the capitalization. The complete, formal name is Microsoft .NET Framework. In references to specific .NET products, .NET is generally separated from the product name by a space, as in Visual Studio .NET. One exception is ASP.NET. more important — Not more importantly, in sentences like: This product is easy to use; more important, it will save you a lot of money. more than vs. over — Use more than to express quantity; over is a spatial reference. There are more than 20 roofers over my head today. multi (prefix) — Don't hyphenate words beginning with multi (for example, multichannel and multiuser) except where necessary to avoid confusion. Avoid inventing new words by combining them with this prefix; for example, use multiple-file rather than multifile. namespace — One word. New Terms — When defining new terms, make them bold (not italic). Don't overdo it: not every new name and term you introduce needs to be boldfaced. And when you do define a term, don't feel compelled to capitalize it (that is, don't capitalize unless there's a reason for doing so). Notes — The preferred treatment of notes is to work them in informally, with something like with "Note that ..." (possibly parenthetically); however, if that interrupts the discussion too much, the following is an acceptable alternative treatment: Note: Here's one way to set off notes from the text. Don't use footnotes. Numerals — In general, spell out all numbers under 10. Use numerals for numbers 10 and higher, except for values of variables or in charts and graphs. For example, you can set the time limit to 2 and see the results after two seconds. Use a comma separator in numerals consisting of five or more digits. There are approximately 10,000 lines of Java code, as opposed to only 5000 lines for our earlier, simpler project. offline — One word, not hyphenated. OK — Not okay. one vs. you — Don't use the formal one, as in "Combining the DHTML object model and XSLT support, one can build highly interactive, Web-based user interfaces." online — One word, not hyphenated. output — Don't use as a verb. Try generate or create, for example. Parts of Articles — See Titles of Articles. pattern engine — Not capitalized. percent — Don't spell this out; use the % symbol instead. plug-in — Capitalize this term only if the plug-in is identified as part of a product, as in the RUP Plug-In. Prepositions — In article titles and similarly capitalized text, capitalize prepositions that are five or more characters long. Business-to-Business XML Standards Definition with the UML Understanding XML Through Osmosis Punctuation — Look up the character in question in this style guide, or see Special Characters for general information. quality — Don't use as a adjective; use, for example, high-quality instead. Quotation Marks — The special ("curly") quotation mark characters are acceptable in a Word document, but don't bother entering the codes for them in HTML. (They won't survive in the final article.) Place commas and periods inside quotation marks except where doing so would affect technical accuracy or clarity. Try to avoid the latter exception by rewording to place the technical content elsewhere in the sentence. "Double quotes on the outside," said Bob. "Bob says 'double quotes on the outside,' but I don't care," said Ralph. Their style is to begin all URLs shown in body text with "http://". Rational Administrator — This product name should be preceded by the. Rational Developer Network — This term should be preceded by the. It's a service mark and so should be followed by SM. It's now acceptable to abbreviate it to RDN after first mentioning the full term, but don't show it in parentheses after the full term; it's a separate service mark, and so should also be followed by SM. The Rational Developer NetworkSM will help you in your development efforts. Resources on RDNSM include articles, documentation, courses, and much more. Rational Product Names — Check Rational's Web site to verify how product names are spelled and capitalized. When referring to a product whose full name begins with Rational (as most of them do), it's acceptable to drop the Rational, but as with any abbreviation you should spell out the full name the first time. Rational RequisitePro — Do not abbreviate RequisitePro to ReqPro. Rational SoDA — Despite the unusual capitalization, treat this as a name, not an acronym. (It presumably stands for "Software Documentation Automation," but it's never explicitly spelled out that way on Rational's Web site.) Rational Unified Process (RUP) — This term should be preceded by the, even when abbreviated to RUP. Since the abbreviation is pronounced "rup," the indefinite article that should precede it is not an but a (as in a RUP artifact). Capitalize RUP terms (or not) as done in The Rational Unified Process: An Introduction, Second Edition. This means making most terms, including the names of the RUP phases (inception, elaboration, construction, and transition), all lowercase. Consistent with the RUP book, the names of use cases should be initial cap, as in the Withdraw Money use case. An exception to following the capitalization in the RUP book is that the names of RUP activities should be initial cap, as in the Identify and Assess Risks activity. Rational XDE — The official full product names for Release 1 are: Rational XDE Professional v2002: Microsoft .NET EditionThey may optionally be followed by "(Release 1)" for clarification. The official full product names for Release 2 and beyond are (using Release 2 as an example): Rational XDE Professional v2002 Release 2 — .NET Edition It's acceptable (although not necessary) to explain the XDE acronym by saying XDE is an eXtended Development Environment. RDN — This is now acceptable as a shorthand way of referring to Rational Developer Network; however, see Rational Developer Network for important related information. References — Articles that refer to books or other resources should end with an area (as shown in the article template) that lists those resources. This area should be labeled in one of the following ways:
References in the body text should be phrased in plain English, not as footnotes or in any special bibliographic style. The first reference to a resource (at least) should have an appropriate link behind it. For articles, the link should not include the quotation marks (or any other surrounding punctuation) around the title. For books, the appropriate link is one that leads to that document on Barnes and Noble's Web site. (For guidelines on links to other resources, see URLs.) Look up the book, get its ISBN number, and plug that number into the following link: http://shop.barnesandnoble.com/booksearch/isbninquiry.asp?isbn=xxxxxxxxxx&from=QQT559 The best source of additional information on XP is Kent Beck's book, Extreme Programming Explained: Embrace Change. Subsequent references may be abbreviated, as in referring to the above book by its title without its subtitle. For the items listed in the Reference/Resources area, use the formats illustrated below. Include the same link as for the reference in the article body.
Note that Rational Developer Network articles (such as the third item above) are not attributed as such in these lists; RDN is the default source that the reader is expected to assume if no attribution is provided.
Other resources besides written works — most typically Web sites, in which case the references themselves are links — don't have to be listed at the end of the article unless you want to expand on them there, such as to describe a site in further detail. requirements creep — Put quotation marks around this term on
first occurrence. (If the level of the article is such that the term
should be explained, here's how Rational Fellow Philippe Kruchten defines it:
"the addition of requirements that
are unnecessary and/or not customer-driven as a project progresses.")
reverse engineering (n), reverse-engineer (v) —
Only the verb is hyphenated.
right-click (v), right click (n) — Hyphenated when used as a verb but not when used as a noun. right-hand, left-hand — Unless a reference to someone's actual hand, use just right or left. RoseScript, RoseScript Editor — A RoseScript is a script created with the RoseScript Editor (for which no longer term, like Rational RoseScript Editor, or shorter term, like Script Editor, is acceptable). The scripting language is simply called the Rose scripting language. Routine, Function, or Method Names — Don't follow these with (); for example, it's "the track method," not "the track() method." (Of course, if you're referring to a call excerpted out of code that literally includes (), which usually denotes the absence of any arguments, you should show it that way.) run time (n), runtime (adj) — Two words when used as a verb, one word when used as a noun. Never hyphenated. RUP — See Rational Unified Process (RUP). Section Headings — Use the traditional style of title capitalization, not sentence-style capitalization, for section headings within articles. See also Prepositions. Don't begin an article with a heading. After the article title, optional subtitle, and author byline (in that order), launch right into the introduction to the article, without an intervening heading. scope creep — Put quotation marks around this term on first occurrence. screenshot — One word. Seasons — Keep in mind that your audience might include people who live in a different hemisphere: don't refer to seasons if you're counting on having them fall during particular calendar months. servlet — Lowercase except when referring to the technology. Tomcat is the official reference implementation for the Java Servlet and JavaServer Pages technologies; it implements the JSP 1.1 and Servlet 2.2 specifications. The features in the latest version of Tomcat include servlet reloading and a new servlet container. Slang — Slang is acceptable in a casual article but not in a formal one (meaning an article that shows Rational Software as the author or that is authored by a Rational employee and is the definitive article on a product). For example, the word grok or the abbreviation of application to app would be acceptable only in a casual article. When in doubt, avoid the slang in question, to prevent confusion by an international audience. Smalltalk — Not SmallTalk. Special Characters — If you type special characters (such as em dash or apostrophe) in a Word document, do so consistently. For example, don't use two hyphens sometimes and the em dash character other times within the same article. Don't use special characters in comments in code; use only ASCII characters. So, for example, quotation marks in comments should be straight, not "curly." Likewise, missing code should be shown with three dots, not the special ellipsis character. In HTML, don't enter the codes for special characters, with these exceptions:
For information about specific special characters, look up the character in this style guide. Start > Programs menu — Note punctuation; not Start|Programs menu. See also Menus. State Names — Spell out state names, except in full postal addresses. sub (prefix) — Don't hyphenate words beginning with sub (for example, subsection and subdirectory) except where necessary to avoid confusion. sync — Not synch. Syntax — The conventions for showing command syntax (and the like) are as follows:
A simple example: chflevel [-force] [-override] -family feature-level vob-selector Table Heads — Use sentence-style capitalization, not title-style capitalization, for column headings within tables. that — Frequently unnecessary; lean toward omitting where not needed for meaning or sentence flow. When you mean so that, however, spell it out rather than shorten it to so. He wasn't told until afterward about the problems the team was having. He wanted to know in advance so that he could take preventive measures. So in the end he decided to go back to freelancing. theater vs. theatre — In general, use theater (although theatre is acceptable when referring to a stage venue). time frame — Not timeframe or time-frame. Titles of Articles — Feel free to give an article a subtitle, but avoid using a "Part" designation unless the later part is expected to be truly a continuation of the earlier part. (For one thing, there's the practical consideration that the later promised part or parts may never get written or may turn out to be something other than planned.) If you do use "Part" designations, the format should be <Title> Part <N>: <Subtitle> Always use Arabic numerals when designating or referring to part numbers; don't use Roman numerals or spell out the numbers. Don't refer to parts of an article as a series of articles, or vice versa. Articles in a series are not continuations of earlier articles; they're simply articles related to the same topic, usually all written by the same author (otherwise every single article on a particular topic would be part of a series on that topic). So there should not be a reference to, for example, "a two-part series"; it's either an article in two parts or a series of two articles. For articles in a series on a particular topic, the titles will most likely correlate in some way to the overall topic of the series; however, each title should stand on its own (and not, say, be the same for all articles in the series, with a different subtitle). There should not be a subtitle (or subtitle-like designation) announcing that this article is one of a series, although it's OK to point this out within the article. (Do not, however, state how many articles are in the series; that's too changeable.) Use the traditional style of capitalization for titles, not sentence-style capitalization. See also Prepositions and Quotation Marks. Titles of Books — See Italic, Prepositions, and References. Toolbox — Use only in referring to the entire XDE Toolbox. To refer to a subset of tools within the Toolbox, use, for example, the Java tools in the XDE Toolbox (not the Java Toolbox). tool set — Not toolset. Trademarks — These guidelines apply only to articles, not to article abstracts (which should not have trademark symbols in them). Trademark symbols should be included after the first occurrence of all Rational trademarks (excluding occurrences in titles or headings). The latest list of Rational trademarks (including service marks) is available from the Rational Web site; a search for trademark will yield a PDF file that can be downloaded. You can also look at how product names are marked on the Web site. Trademark symbols only need to be included after third-party trademarks if a particular third party has requested or required it of Rational. One such company is Sun; their Web site provides further information (including that it suffices to use the TM symbol for all their trademarks, and not worry about which ones might be registered). The primary Sun trademark that comes up in Rational Developer Network articles is Java; to check whether other Sun product names are trademarks, look around on their site (to see how they've marked them). Note that company names used as such are not trademarks, but a company's name as part of a product name may be a trademark. Whether for Rational or third-party trademarks, the inclusion of the symbols is all that's needed; no trademark legend (saying who owns the trademarks) needs to be included in the article. Strictly speaking, every trademark should be used as an adjective and not a noun (for example, the Java language instead of just Java). This isn't always easy or practical, but it should be done to the fullest reasonable extent, especially the first time or two that the term is used. Also, trademarks should not be used in the plural or the possessive. In HTML, the trademarks symbols should be entered as follows:
tradeoff — Not trade-off. T-shirt — Not t-shirt. (This comes up when offered as an incentive to authors, survey takers, and the like.) Underline — Do not use. (Its use is reserved for representing links.) Unified Modeling Language (UML) — Precede this product name by an article when first spelled out, whether abbreviated or not. The Unified Modeling Language (UML) is a graphical language for visualizing, specifying, constructing, and documenting models of a system. The UML provides a standard means of writing the system's blueprints. URLs — Except where noted otherwise, the following guidelines apply to URLs that are appropriate for the reader to link to. (This is not the case, for example, for URLs representing namespaces within an XML document.)
Pulsipher and Buckley founded QOSES in Tracy, California. Darren's biography is available on the QOSES Web site. Along these lines, don't say something like "Click here to download this spreadsheet" within prose paragraphs (as opposed to tacked on at the end of an article, where this wording is acceptable). An alternative for this example would be "You can download this spreadsheet." Keep URLs at as high a level as reasonable, since many sites tend to change their structure at lower levels (making the link obsolete). It's generally dangerous to go down more than one level below the home page. By following links on the home page (or other high-level page) that you refer to, the reader should be able to easily find the sought-after information. All links should work for anyone registered with the Rational Developer Network. They shouldn't require a developer to have some special standing with Rational Software. URLs that aren't appropriate for hiding (that is, that are part of the text of the article) will usually be code excerpts and so should be in the code font. For those few cases where this isn't so, use the normal body font. As shown in Listing 1, the track method is from a class identified with the XML namespace http://www.psol.com/soap/track. The object of the call to track resides on a Web server at address http://catwoman.pineapplesoft.com/soap/rpcrouter. This latter URL is derived from information in the HTTP header; it doesn't appear in the XML document.See also Links. use-case model — Hyphenated. user-experience model — Hyphenated. user ID — Two words. utilize — Avoid in favor of use. Version Numbers — Letters following Rational product version numbers should be capitalized, as in Rational Rose 2001A. Visual Basic .NET — Not Visual Basic.NET. Do not abbreviate to VB .NET or VB.NET. Visual Studio .NET — Not Visual Studio.NET. Do not abbreviate to VS .NET or VS.NET. we — Don't use to mean the Rational Developer Network (or any other part of Rational) without clarifying that that's what you mean (as in "At Rational, we ..."). Web — Capitalized. WebSphere Studio Application Developer — Use Application Developer for short, not WSS AD or WSAD. (This comes from IBM via Khawar Ahmed of Rational.) WebSphere Studio Workbench — Do not abbreviate to any acronym (WSW, WSWB, or whatever). This IDE from IBM is based on (not equivalent to) Eclipse. Eclipse is a platform developed independently of IBM. Web page — This is the preferred term for referring to any level below the top level of a Web site. For example, http://www.w3c.org is the URL for the W3C's Web site, but http://www.w3c.org/xml/ is the URL for the W3C's XML Web page. Web site — Two words. whitepaper — One word. Windows 2000 Professional — Not Win2K or w2k. XML — Stands for Extensible Markup Language, not eXtensible Markup Language. For how to refer to XML elements in text, see HTML Elements. you — Use the second person freely. Don't use the formal one, as in "In this way, one can build highly interactive, Web-based user interfaces." Zip disk — Note capitalization. ZIP file — Note capitalization. |