2 Writing a Technology Description

This list provides a quick overview of the process involved in creating a technology description; details are to follow:

1. contact us
2. obtain template
3. write description
4. submit description
5. undergo review cycle
6. enter maintenance phase

  If you are interested in submitting a technology description, please send email to str@sei.cmu.edu.

  Each technology description follows a structured template; to obtain a copy of the template, send email to str@sei.cmu.edu or refer to /str/descriptions/template/template.html.

A description of each section of the template follows.

Status. Each technology description begins with a status indicator. This status indicator provides an assessment of the overall quality and maturity of the technology description. One of four indicators is assigned by the STR staff: Draft, In Review, Advanced, or Complete. All technology descriptions begin in Draft status. (For a more detailed description of these states, please see Section 2.5.)

Note. Include this section if prerequisite or follow-on reading is recommended. The prerequisites are usually technology descriptions that provide an overview of the general topic area and establish a context for the different technologies in the area.

Purpose and Origin. This section should provide a general description and brief background of the technology. It should include what capability or benefit was anticipated for the technology when originally conceived, and identify common aliases for the technology as well as its originator(s) or key developer(s) (if known).

Technical Detail. This section should answer--succinctly--the question, "What does the technology do?" It should include the salient quality measures (see Taxonomy Categories) that are influenced by the technology in all situations and describe the tradeoffs that are enabled by the technology. It may also provide some insight into why the technology works and what advances are expected. Since the STR is not a "how-to" manual, do not provide any implementation details.

Usage Considerations. This section should provide insight for the use of the technology. Issues to be addressed include

• example applications into which this technology may be incorporated (or should not be incorporated); for instance, "this technology, because of its emphasis on synchronized processing, is particularly suited for real-time applications"
• quality measures that may be influenced by this technology, depending on the particular context in which the application is employed

Maturity. The purpose of this section is to provide an indication as to how well-developed the technology is. (A technology that was developed a year or two ago and is still in the experimental stage--or still being developed at the university research level--will likely be more difficult to adopt than one that has been in use in many systems for a decade.) It is not the intent of this document to provide an absolute measure of maturity, but to provide enough information to allow the reader to make an informed judgment as to the technology's maturity for their application area. Details that will help in this determination include

• the extent to which the technology has been incorporated into real systems, tools, or commercial products
• the success that developers have had in adopting and using the technology
• notable failures of the technology (if any)

Other information that might appear in this section includes trend information, such as a projection of the technology's long term potential; observations about the rate of maturation; and implications of rapid maturation.

Costs and Limitations. This section should point out limitations and costs of using a particular technology. Some examples of the kinds of costs and limitations associated with a technology are the following: a technology may impose an otherwise unnecessary interface standard; it might require investment in other technologies (see Dependencies below); it might require investment of time or money; or it may directly conflict with security or real-time requirements. Specific items to discuss include

• what is needed to adopt this technology (this could mean training requirements, skill levels needed, programming languages, or specific architectures)?
• how long it takes to incorporate or implement this technology?
• barriers to the use of this technology
• reasons why this technology would not be used

Dependencies. This section should identify other technologies that influence or are influenced by the technology being described. You should only include dependencies for which significant influence in either direction is expected. You should also provide an indication as to why the dependency exists (usually in terms of quality measure or usage consideration). If the dependent technology appears in the document, provide a cross-reference to it. Omit this paragraph if no dependencies are known.

Alternatives. An alternative technology is one that could be used for the same purposes as the technology being described. A technology is an alternative if there is any situation or purpose for which both technologies are viable or likely to be considered candidates. Alternatives may represent a simple choice among technologies that achieve the same solution to a problem, or they may represent completely different approaches to the problem being addressed by the technology.

For each alternative technology, provide a concise description of the situations for which it provides an alternative. Also provide any special considerations that could help in selecting among alternatives. If the alternative technology appears in the document, provide a cross-reference to it.

Alternative technologies are distinct from dependent or complementary technologies, which must be used in combination with the technology being described to achieve the given purpose.

Complementary Technologies. A complementary technology is one that enhances or is enhanced by the technology being described, but for which neither is critical to the development or use of the other (if it were critical, then it would appear in the "Dependencies" section above). Typically, a complementary technology is one that--in combination with this technology--will achieve benefits or capabilities that are not obvious when the technologies are considered separately. For each complementary technology, provide a concise description of the conditions under which it is complementary and the additional benefits that are provided by the combination. If the complementary technology appears in the document, provide a cross-reference to it.

Taxonomy Categories. We have created several taxonomies to categorize technology descriptions. These taxonomies are:

• Application taxonomy. This taxonomy refers to how this technology would be employed, either in support of operational systems (perhaps in a particular phase of the life cycle) or in actual operation of systems (for example, to provide system security).
• Quality measures taxonomy. This is a list of those quality attributes (e.g., reliability or responsiveness) that are influenced in some way by the application of this technology.
• Computing Reviews taxonomy: This taxonomy describes the technical subdiscipline within Computer Science into which the technology falls. The category is based on the ACM Computing Reviews Classification System developed in 1991 (and currently undergoing revision). A complete description of the Classification System and its contents can be found in any January issue of Computing Surveys or in the annual ACM Guide to Computing Literature.

For each of these taxonomies, you should suggest terms under which your technology description can be classified. See our Web site for the full taxonomies: /str/taxonomies/

References and Information Sources. The final section in each technology description provides bibliographic information. You should include sources cited in the technology description, as well as pointers to additional resources that a reader can go to for more information. You should designate one to four key references with an asterisk (*). Key references are those that will best assist a reader in learning more about the technology.

Current Author/Maintainer. The author(s)/maintainer(s) of the current version of the technology description are listed in this section. The only exceptions are Draft technology descriptions, which are published without an author's name.

Internal Team Reviewer(s). Name(s) of those on the project team who reviewed the technology description. (This section will not appear in the published version of the technology description.)

External Reviewer(s). This section contains names of external experts who have reviewed this technology description. If no "External Reviewer(s)" heading is present, then an external review has not occurred. Note: if the preface "candidate" is used, the individual has been suggested as a reviewer, but has not yet agreed to participate.

Keyword Index. You should provide a list keywords under which this technology may be indexed (or indicate those by making a notation in the text). This section of the templates indicates whether keywords were chosen for this technology description. This step is not necessary until a technology description reaches the "In Review" state. (This section will not appear in the published version of the technology description.)

Future. This section includes items to be considered as part of the future evolution of this technology description. (This section will not appear in the published version of the technology description.)

Background/Support. Provides an explanation for some key piece of information in the technology description. (This section will not appear in the published version of the technology description.)

Modifications. This area lists the modification history of the technology description and includes the names of contributing authors from earlier versions of the description.

Pending. A known item that needs to be addressed in future versions of the description. These are posted (when known) so that the reader can pursue these items on their own if necessary.

We ask that you follow these guidelines when writing and submitting new material to the STR. If you have any questions about these guidelines, send email to str@sei.cmu.edu.

2.3.1 Electronic Format

All technology descriptions should be submitted in ASCII (plain text) on a disk or by email. Note: You may develop the description in a word processor if you prefer, but you should save your technology description in a plain text format before you submit the file.

2.3.2 Graphics

Any graphics used in technology descriptions should be drawn in either PowerPoint or FrameMaker and submitted on a disk or by email.

2.3.3 Cross-References and Minor Formatting

When working in ASCII text, use the following notations to indicate cross-references and formatting conventions.

To denote cross-references (to other technology descriptions, etc.), use the format [xref: <name of technology description, heading, etc.>]. For example

See object-oriented programming languages [xref: object-oriented programming languages] for more information about this topic.

The Cleanroom [xref: Cleanroom] technology description covers this in more detail. To denote bold and italics, use the formats <b text to be bold /b> for bold text, <i text to be italicized /i> for italicized text. For example

This is <b not /b> an object-oriented programming language.

This technology supports <i maintainability /i> of large-scale software systems. To denote terms you would like to have included in the Keyword Index, use the format [index: <term to be indexed>].

See object-oriented programming languages [index: object-oriented programming languages] for more information about this topic.

2.3.4 References and Information Sources

Please follow these guidelines when including references and information sources in your technology descriptions.

• Include only published documents, i.e., do not cite draft documents or those "to be published." If you must reference an unpublished document, use a footnote.
• Include only publicly-available documents.
• To the extent possible, follow the reference guidelines below.

Note: Don't forget to indicate key references with an asterisk.

Citations in text should appear in brackets and contain the last name of the author, editor, or publishing organization by which the document is identified in the reference list followed by a space and the last two digits of the year of publication.

[Brown 89]

[IEEE 90]

The only legitimate function of a citation is to refer the reader to the list at the end of the document. Therefore, a citation should not be a semantic element of the sentence in which it occurs. All sentences should be complete without citations. [wrong] The process is described in [Brown 89].

[right] Brown has described this process [Brown 89].

For consecutive citations, use a single bracket.

[Brown 89, IEEE 90]

For consecutive citations by the same author, use a single bracket but enclose the complete citations:

[Brown 89, Brown 90]

The following examples offer formatting information for several types of references. Please make an effort to include all of the information requested for each reference; we need to have the information before the technology description can be published.

Citing Books
Template
[<citation>]	<last name>, <first name> <middle initial>. <title>. <city, state of publication>: <publisher's name>, <date of publication>.
Example
[Yourdon 89]	Yourdon, Edward N. Modern Structured Analysis. Englewood Cliffs, N.J.: Prentice-Hall, 1989.

Citing Technical and Research Reports
Template
[<citation>]	<last name>, <first name> <middle initial>. <title of report> (<report number>, <DTIC number when available>). <city and state of publication>: <publisher's name>, <date of publication>.
Example
[Graham 89]	Graham, Marc H. Guidelines for the Use of SAME (CMU/SEI-89-TR-16, ADA228027). Pittsburgh, Pa.: Software Engineering Institute, Carnegie Mellon University, 1989.

Citing Journals
Template
[<citation>]	<last name>, <first name> <middle initial>. "<title of article>." <journal title> <volume number>, <number of issue> (<month or season and year of issue>): <inclusive page numbers>.
Example
[Bohm 66]	Bohm, Charles. "Flow Diagrams, Turing Machines, and Languages With Only Two Formation Rules." Communications of the ACM 8, 5 (May 1966): 366-371.

Citing WWW sites
Template
[<citation>]	<last name>, <first name> <middle initial>. <title> [online]. Available <FTP/Telnet/WWW>: <<URL>> <(year of publication)>.
Example
[Rogers 92]	Rogers, Robin. User's Guide to the Beaches of Southern California [online]. Available WWW <URL: http://www.acme.com:/rogers/docs/beaches/so_cal/ug> (1992).

Citing Meetings and Symposia
Template
[<citation>]	<last name>, <first name> <middle initial>. "<title of the article>," <page numbers>. Proceedings of <name of the meeting or symposium>. <city and state of meeting or symposium>, <date(s) and year of meeting or symposium>. <city, state of publication>: <publisher's name>, <date of publication>.
Example
[Kaiser 89]	Kaiser, G. "Mechanisms," 256-275. Proceedings of the 5th International Software Process Workshop. Kennebunkport, Maine, Oct. 10-13, 1989. New York: IEE Computer Society Press, 1990.

2.3.5 Editing

All technology descriptions will be edited for consistency and conformance to the SEI Style Guide. Any substantial edits will be subject to the approval of the author and/or the STR review staff. To obtain a copy of the style guide, send mail to str@sei.cmu.edu.

  See Appendix B for a pre-submission checklist. By following the checklist, you can make sure your submissions are complete before you send them in.

Email submissions to: str@sei.cmu.edu

Mail submissions to: Lauren Heinz
Software Engineering Institute
Carnegie Mellon University
4500 Fifth Avenue
Pittsburgh, PA 15213-3890

  In order to sustain credibility and accuracy, each technology description goes through a review process. Please see Appendix C for a copy of the checklist used by reviewers. (The checklist may help you as you write your technology description.)

The review cycle includes the following steps:

• review by technology cluster leader (if one exists)
• internal team review^*
• external review

While in the review cycle, a technology description progresses through the following stages: Draft, In Review, Advanced, and Complete. Each of the four status indicators is explained below:

Draft technology descriptions have the following attributes:

• They need more work.
• They have generally not been reviewed.
• Overall assessment: While technology descriptions labeled "Draft" will contain some useful information, readers should not rely on these descriptions as their only source of information about the topic. Readers should consider these descriptions as starting points for conducting their own research about the technology.

In Review technology descriptions have the following attributes:

• They are thought to be in fair technical shape.
• They have begun an internal review cycle^*.
• They may have major issues that must be resolved, or some sections that may require additional text.
• Relevant keywords have been added to the Keyword Index.
• Overall assessment: Readers can get some quality information from these, but because these descriptions have not been completely reviewed, readers should explore some of the references for additional information and consider conducting their own research about the technology.

Advanced technology descriptions have the following attributes:

• They are in good technical shape.
• Internal review has occurred.
• There are minor issues to be worked, but it is generally polished.
• They are subject to additional review by external reviewers.
• Relevant keywords have been added to the Keyword Index.
• Overall assessment: These descriptions are in rather good shape, but because they have not been through external review, readers should exercise some caution.

Complete technology descriptions have the following attributes:

• At least one expert external review has occurred, and issues from that review have been resolved.
• Relevant keywords have been added to the Keyword Index.
• No additional work is necessary at this time.
• Overall assessment: These technology descriptions are believed to be complete and correct. They would be revised in the future based on additional external reviewers, new information, and public feedback.

  Please note: Once the technology description has been formatted in FrameMaker and coded in HTML, we will accept submissions as hard-copy markups only, unless the technology description has been sufficiently revised to warrant total replacement.

^* Internal review cycle refers to the review process that takes place within the development/editorial team.