FW: Specialize but not right away

["Esrig, Bruce \(Bruce\)" <esrig@lucent.com>]

Please review the next soapbox article ...

Bruce

-----Original Message-----
From: Esrig, Bruce (Bruce) 
Sent: Thursday, August 10, 2006 12:41 PM
To: 'Carol Geyer'; 'Scott Prentice'; 'Jennifer Linton'
Cc: 'JoAnn Hackos'; 'Don Day'; 'Michael Priestley'; 'Adi Kabazo'
Subject: Specialize but not right away

Draft of go-slow-on-specialization article.

XMetaL enthusiasts will notice that I used the out-of-the-box PDF
generation from XMetaL Author DITA edition.

Best wishes,

Bruce

when-to-specialize.pdf

<?xml version="1.0"?>
<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<!-- Created with XMetaL 4.6 (http://www.xmetal.com) -->
<dita><concept id="concept_BE2180630C0D41C5A3CF76AE0E4D1853"><title>When to specialize</title><shortdesc>Specialized information types are used to formalize established best practices. It is important not to specialize too soon.</shortdesc>
<conbody><p>Many organizations are attracted to DITA because the DITA content model is systematic. Concept, task, and reference topics are each specialized information types. What they have in common is specified in their common parent, the &lt;topic&gt; element.</p><p>DITA is also extensible. An information architect can define new specialized information types to capture best practices that are in common use, or that ought to be used more commonly, or that are explicitly required by a style guide.</p><p>It is important to be conservative in defining new information types. There are substantial costs when a new information type is introduced, and later, it  can be hard to make changes.</p><p>We recommend that organizations migrating to DITA adopt the base language first. As best practices in the use of the base language become established, they can be reviewed. When a best practice reflects a broadly applicable, stable, and structurally sound design, it can be implemented as a specialized information type.</p><section id="section_2FF653F383DA44BD9FBF5DD07CE3EBA7"><title>The base language</title><p>The base DITA language offers the essential capabilities required for topic-based authoring:</p> <ul><li id="li_69F645237DE848C8ABA02BD8ACAB424E">Paragraph content and inline markup.</li><li id="li_D500C6C1B86E43F2BF0EB991A66D8AA5">Unordered lists, ordered lists, figures, and notes</li><li id="li_BE0A203AB6E14BEBA02259BB639507F6">Topics and labeled sections within a topic</li><li id="li_7A715148D871404FBAA687C3DDC2A0B4">Maps to organize topics into sequences and hierarchies</li>
</ul><p>The base language takes advantage of specialization:</p><ul><li id="li_CCB63EA7CFF94C15B5E60951DB1B5F59">Concept, task, and reference are types of topics</li><li id="li_3C087308F6E64B64BC008B9D5C3DA816">A parameter name is a type of keyword</li>
<li id="li_4B4084BD124A4CC3A6F46854E709A497">An imagemap is a type of figure</li></ul></section><section id="section_38262DB93C9E4042A83977B6974B732C"><title>Reasons to specialize</title><p>There are several purposes that can justify a specialized information type:</p><simpletable id="simpletable_A6EA46EF819C462392EFA039120DA5A6"><sthead><stentry><p>Kind of specialization</p></stentry><stentry><p>Reasons</p></stentry></sthead><strow><stentry><p>Structural specialization</p></stentry><stentry><p>To restrict the variety of structures that are permitted.</p><p>To provide consistent input to a page formatting or presentation system.</p></stentry></strow><strow><stentry><p>Domain specialization	</p></stentry><stentry><p>To establish a new collection of elements useful in a particular domain.</p><p>To enable specialized formatting appropriate for information in a particular domain.</p></stentry></strow></simpletable><p>Concept, task, and reference are specialized both for structural reasons and to establish distinct authoring practices for the different information types. Each of these three topic types differs from the others not only in what information they should contain, but also in the structure of the information. A task is expected to contain a sequence of steps. When writing a concept topic, a sequence of steps can be described using an ordered list. But if it is intended that the steps be performed, they should be presented separately in a task topic.</p><p>Since a parameter name is formulated as a specialized type of keyword, it inherits the processing behavior of keyword. When processed, the contents of any &lt;parmname&gt; element that occurs in the body of a topic are used to generate output. The same is true of the contents of a &lt;keyword&gt; element in that context. The advantage of using a specialized type is that &lt;parmname&gt; can be rendered using a distinctive typeface, and this can be done consistently for all parameter names, as long as they are marked using the &lt;parmname&gt; element.</p><p>In the case of image maps, the base language actually provides flexibility in the definition of figure specifically to allow for the variety among ways of presenting figures. Image maps contain areas. Each area contains a shape declaration, the coordinates of the shape, and a link to go to if the area is selected by an end user. The image map contains a regular structure that provides consistent input for a downstream presentation system. The result is not only specialized formatting but specialized behavior for the end user, managed by the presentation system (in this case, a browser).</p></section><section id="section_D3EC58B4A6514B2BB4F357A3C283EB63"><title>Defining a specialization</title><p>In order to define a specialized information type, several facts need to be determined:</p><ul><li id="li_1B6795B6FC2742B0A9C30755A3081813">The structures that will be permitted</li><li id="li_4A1093D1E5464A479368E6907BF5B2B5">The contexts in which those structures will be permitted</li><li id="li_C58B4B73533747019C1B62170FD1CECB">The processing that is expected</li><li id="li_5C5F67B44912416AB971B90FAF42514F">A more general element to specialize from</li></ul><p>Also, certain steps and resources are required for a successful rollout:</p>
<ul><li id="li_A99FB8F48416455EBD1201274286631D">The technical steps to implement the specialization</li>
	<li id="li_9A52C4A1C196464CAF866E65D7B39887">Guidelines for users regarding the capabilities and use of the specialization</li>
</ul><p>The two activities that involve the most commitment are implementing the specialization and ensuring that the intended use is adopted. Once a specialization has been rolled out, it is comparatively difficult to make changes to it. Simple extensions can sometimes be rolled out easily, but adjustments and restrictions can require a full migration of the affected content. Even if the migration can be automated, most organizations would want to avoid that cost.</p></section><section id="section_F6E85D0D30DB4728977AF225AB8A6B82"><title>Developing confidence in a proposed specialization</title><p>The low-cost way to develop a specialization is to implement it as a template first.</p><p>A template is an example showing the approved method of structuring certain information, together with guidelines explaining the structure and any associated criteria. When should this structure be used? What components are required and in what order? What components are optional and where may they appear?</p><p>The template and its associated guidelines should be reviewed on two levels. The template should be checked in principle against the purposes for which it was defined, and the guidelines should be checked to ensure that they accurately state where the new information structure can be used.</p><p>Second, the template should be checked against actual uses. Are there cases where the template is not adequate? What is being added or modified? Should those changes be incorporated into the template and/or the guidelines? Should those practices be forbidden? How consistently is the template being used? What does the feedback about use and non-use of the template indicate?</p><p>These principled and practical reviews of a template and its associated guidelines should be conducted over a period of time. The issues that are raised should be put in context by considering what is required to have a sound definition of an information type. If the template and its guidelines can be brought in line with the requirements for defining and information type, then it makes sense to consider defining a specialization. If not, imagine how much trouble has been saved by not specializing too soon!</p></section></conbody></concept></dita>