Chapter 13. Training and Support

Table of Contents

13.1. Audiences for the Training
13.2. User Support
13.3. Phase 1: Initial Training
13.3.1. Introduction
13.3.2. Lectures and Paper Exercises
13.3.3. Computer Labs
13.3.4. Conclusion of Initial Training
13.4. Phase 2: Training Followup
13.5. Phase 3: Refresher Course
13.6. Phase 4: Quality Inspection of Documents
13.7. Phase 5: Information and Training on DTD Updates
13.8. Training Program Administration
13.8.1. Prerequisites
13.8.2. Number of Participants
13.8.3. Choice of Trainers
13.8.4. Length and Organization of the Training
13.8.5. Training Materials
13.9. The Learning Curve
13.9.1. Time Span
13.9.2. Productivity Assessment
13.10. Training Challenges

Teaching people how to mark up documents using a DTD is a fundamental part of the successful launch of an SGML project, and it should be given just as much attention and care as the previous phases of development. However, it poses a challenge not found in the other phases: The people involved often resist new concepts and tools because they perceive them as threats to their jobs. As a result, there are two aspects to DTD training, the intellectual and the psychological. In this chapter we address both aspects of the problem, to help you ensure that your trainees get into “success mode.

This chapter is meant for the person in charge of organizing the DTD training. It describes how to plan and deliver a training program for people who must use a DTD to mark up the documents they write. We explain how to organize DTD training sessions by:

In Section 13.9, “The Learning Curve” we provide some figures, drawn from real-life experience, that show what to expect in terms of productivity loss, learning, and assimilation time span. Section 13.10, “Training Challenges” concludes by presenting suggestions for overcoming the common difficulties of DTD training.

Organizing a training program requires you to adapt the training sessions to your situation according to several factors:

Because the variety of possible training curricula is very wide, we have chosen to limit our suggestions to the most common cases and to provide practical information that you can either use directly or extrapolate from.

For example, we assume that the trainees have already mastered the content of the documents they are likely to model and mark up. We also assume that the trainees will ultimately be using SGML-aware editing tools that provide markup assistance and validation, and that they are in charge of producing new material, rather than converting existing documents or “post-tagging” existing contents that they do not fully understand. (Note that training for this last situation is a completely different problem that needs to be handled separately.)

In addition, for simplicity we assume that only one DTD is being taught. In some cases, the users need to learn several DTDs for different document types, but usually each DTD is introduced at a different time, in which case we suggest starting from the commonalities between the known DTD and the new DTD and then teaching what the differences are.

This chapter does not cover training on SGML concepts. The material in Chapter 1, Introduction to SGML provides an example of the kind of conceptual training that might be helpful for authors.

Following are basic strategies for effective DTD training.

13.1. Audiences for the Training

The primary audience for DTD training includes the people who create the content (authors, writers, contributors), those who review and modify it (reviewers, editors, production specialists, possibly literallayout artists), and translate it into other languages. However, a secondary audience, including the system administrator, any database administrators, and the managing editor or project manager, may also need training.

The goal for the primary audience is to make them proficient in marking up texts using the DTD, and confident in their ability to find a solution when they encounter markup or technical problems. The difficulty of this goal largely depends on the cultures, motivations, and abilities of these people.

The secondary audience doesn't need the same level of proficiency in the use of the DTD. However, solid knowledge of the DTD is useful to the administrators when they are asked to diagnose and solve a problem on the files or on their content, as well as to document project managers who must mediate disputes when there are DTD or tool problems.

The people who will test and review the draft DTD are usually members of the primary audience, and they may need a slightly different kind of training, which has effective DTD review as its main goal. It is difficult to organize training for testers because they are supposedly already very familiar with what they are supposed to review. If you need to teach the DTD to reviewers in order for them to review it, chances are they will not be knowledgeable enough to carry out the task. However, during conversion or markup of test documents, you can simply conduct normal DTD training for those testers who were not part of the design process. This may result in building a draft training program based on the draft DTD and draft documentation. The organization can be similar to the users' training described in the rest of this chapter, though it is likely to be less fleshed out. Fortunately, testers are usually highly motivated and quick to grasp all the new concepts.

13.2. User Support

Support is invaluable to the SGML project, and to the training effort specifically. DTD user support must start to be provided as soon as the initial training is over and it goes on indefinitely, with a significant decrease after two to three months.

The amount of support you will have to make available is strongly related to the quality of the training and the level of autonomy the trainees have gained during the lab sessions. It is therefore useful to have the people in charge of the support participate in the definition and the evaluation of the training sessions.

Just as for the training, there are usually two levels of support that need to be given: the psychological and the technical.

Users will need direct help in marking up documents. This help should be provided in close coordination with the DTD training, and it must be nearly instantaneous. We have found that the psychological dimension here is crucial. When faced with markup problems, users often lose their self-confidence and start deprecating their ability to choose and insert markup. By contrast, when faced with technical problems they usually feel able to ask for help and they don't blame themselves for their difficulties.

Consequently, it is important to choose support people not only for their theoretical competence but also for their communication abilities and their ease at psychologically supporting the users. This kind of support is the kind most requested in the early days or weeks of deploying your SGML editing environment, unless the system has other technical problems.

The second level of support involves technical expertise. Because of the level of validation usually supplied by an SGML editing environment (whether it offers real-time markup checking or batch checking after documents are written), the “parser” expert and the system administrator are crucial figures. The technical support people will also take over all the problems associated with the use of the editing tool, which is why it is useful to have these people involved in the lab sessions in the training.

With these two types of support available, you are prepared to face the difficulties of the learning curve. After a short period of exhilaration, the real work of producing real documents takes a toll on the authors; often, after three or four weeks, everything suddenly blurs in their heads. The temptation is great for them to just give up, which is why support must be readily available during these periods.

After this crisis stage, either the authors have successfully overcome their apprehensions, in which case they need little more support, or they haven't, in which case the support team will bear all the weight of convincing these people to go on even if they feel they do not understand how the authoring and markup processes work and bring them to an acceptable level of proficiency. Unfortunately, this is a long process that can take several months.

Once training has been completed, the support team may also help the authors review their markup as part of the post-training quality inspection of documents.

13.3. Phase 1: Initial Training

The first phase of the program is what people usually think of as “the training.” It takes place in a room with a teacher and the usual training equipment such as an overhead projector, plus computers for lab work. The initial training usually involves three types of activities: an introduction, lectures and paper exercises to teach the DTD, and computer labs to learn how to use the DTD with the available tools.

13.3.1. Introduction

This period may last from one hour to half a day, depending on the amount of convincing you need to do. It usually includes:

  • A presentation on the project to migrate to SGML

  • An introduction to the underlying principles of SGML: why SGML, who uses it, what are its strengths, a bibliography for good reference information, and so on

  • A presentation on the expected gains for the company or the organization, and the benefits people in the room will individually get in the mid term or the long term

  • A description of the foreseen difficulties, why they exist, how long they usually last, the best way to overcome them, and how much effort people will have to put in

  • The training program's specific goals, outline, and schedule, and what will be expected of the trainees

Now is the perfect time to introduce the notion of Tag Abuse Syndrome to the trainees and to encourage them to take responsibility for the markup in their documents. The following “dos and don'ts” list can serve as a reminder.

  • Do:
    • Become familiar with the DTD you will be using and learn the distinctions it offers.

    • Use the most precise and accurate available construct in the DTD.

    • Choose an appropriate existing construct and extend its semantic role if the DTD's markup isn't powerful or precise enough.

    • Use comments to explain your markup choices.

    • Use standard entities and element templates or templates where they are available.

  • Don't:
    • Use an element to get its formatting effect.

    • Use elements with the same formatting effect interchangeably.

    • Fail to mark up information just because you're unsure what markup to choose or because the markup seems difficult; ask for help instead.

At the end of this part, the trainees should know that what awaits them in the training may not necessarily be easy, but should feel confident in their ability, with the trainers' help, to overcome the difficulties and become more qualified in their jobs, and that, in the long run, the effort should be worthwhile.

13.3.2. Lectures and Paper Exercises

Each section of initiation to the DTD ideally includes both a lecture and one or more exercises to perform with a pencil and paper. The best method is to alternate short sessions of theoretical presentation of content with the immediate application of this knowledge in an exercise.

The usual progression of topics roughly follows the layers of the actual markup model:

  • Global presentation of the DTD

  • The document hierarchy, with special attention given to the metainformation

  • The information units, by class

  • The data-level elements, by class

  • Linking processes

  • Miscellaneous topics

13.3.2.1. Global Presentation of the DTD

Each step of the training should always be presented in reference to the documents the trainees know well from their current practice. This may generate questions like “What about handling photographs?” and “How do I make sure the table and the explanation face each other on the page?” These questions are often unrelated to the DTD itself, but they are always related to the authoring and production of documents. It's a good idea to defer answering these questions until the trainees have more of a base of knowledge, writing down the questions as you go and crossing them off the list once they are addressed.

To make a global presentation of the DTD, present the following topics using existing documents as examples:

  • The types of documents covered by the DTD

  • The overall hierarchical structure of the documents and the main similarities to and differences from the structure of the documents they have been accustomed to

  • The vertical organization of the documents: the hierarchical structure, the information units, the data-level elements, and the linking structures

  • The differences between the reference DTD and the authoring DTD and their reasons, if any differences exist

13.3.2.2. The Document Hierarchical Structure

Now you're ready to begin teaching specific features of the markup model. Along with real-life examples, the best way to convey the document hierarchy's organization and constraints is to use the tree diagram notation. Here is one way to proceed:

  1. Ask the trainees to state in English their guesses for the hierarchical structure rules, to demonstrate how easy it is to describe them clearly, thoroughly, and concisely.

  2. Teach them the basics of the elm tree diagram notation.

  3. Show them the tree diagrams for the document hierarchy (by referring to the DTD user's guide, if possible), and have them interpret the trees out loud. If the trees don't show the actual generic identifiers along with the descriptive names of the elements, you'll need to provide the short-form names.

  4. Immediately provide a few samples of varied document parts on paper and ask the trainees to mark up the hierarchical structure with pencils, remembering to open and close each element and to use the correct element name. There are two ways to go about this, each with advantages and drawbacks:

    • You can use reproductions of whole documents, as shown in the training exercises in Section 4.1.2.2, “Recognizing Nested Containment”. These have the advantage of realism, but may confuse trainees because they will likely contain more than just “hierarchy” elements, such as paragraphs and lists. Either you will have to cover these elements now too, or you will have to explain how to skip them.

    • You can use reproductions of tables of contents. These have the advantage of neatly distilling most of the important document hierarchy without involving other elements. However, because the only evidence of a division in a table of contents is the title of that division, this exercise could contribute to confusion about whether a division is a container or just a heading.

      Whichever approach you choose, plan to use the same documents throughout the paper and computer exercises.

To teach the whole document hierarchy, you'll need to explain how to supply metainformation. The nature of metainformation is usually very different from that of hierarchical structure. For example, it usually relies heavily on attributes and must be explained by reference to the processing that the documents will undergo. Thus, you'll need to switch mental gears between the two topics.

13.3.2.3. The Information Units and Data-Level Elements

Within the document hierarchy, usually there isn't much markup choice available. Once you begin to cover elements in the information pool, however, choosing the right markup and choosing to apply markup become major themes, particularly if your documents have been automatically converted to SGML and either have lost important structure or never had it in the first place.

First, you need to explain the differences between the IU and data levels and define your usages of these names. Usually the difference is intuitive to trainees, though people with only WYSIWYG experience may try to reduce the meanings to “paragraph styles” and “character styles,” which isn't quite appropriate.

Then, you need to present each level in turn: first IUs, then data-level elements. As before, have trainees interpret the tree diagram for each element. As much as possible, try to move from the most frequently used elements to the rarest ones, and from the simplest to the most complex. Typically, paragraphs are both the most frequently used and the simplest IU, and lists are a close second. In some DTDs, lists can be quite complex; in this case, it makes sense to teach, for example, “notes” and “cautions” or other simpler IUs before lists.

Try to introduce whole classes of elements at one time so the elements can be understood partially in terms of each other, and teach strategies for choosing among them. For each element class, use paper exercises with sample document fragments to reinforce what has been learned and to show how the markup gradually gains in completeness and quality. Any IUs that involve complex authoring interfaces, such as tables, can be introduced now or can be introduced during the computer labs.

At the end of the section on IUs, make sure the trainees' “hand-tagging” on paper is accurate. If the paper exercises have gotten tedious, you can switch to the computer lab sessions (discussed in Section 13.3.3, “Computer Labs”) before beginning the data-level elements, because the trainees now know enough to start marking up text using editing software.

Presenting the data-level elements is a bit different from presenting the IUs. Because the data-level elements tend to have little internal structure, you can spend your time more profitably on discussing the differences among elements in a class and describing the processing expectations for each element. Whichever elements you concentrate on the most will be the most correctly used. Unless you teach this part in a lively manner with discussions, expression of disagreement, and so on, it can quickly become boring.

Have the trainees apply this new knowledge to marking up data-level components in the sample documents that they now are quite familiar with. Correct or suggest alternative markup along the way.

13.3.2.4. The Linking Processes

The topic of “linking,” or putting two or more pieces of information in association with each other, crosses the structural organization of the DTD. It is difficult to give specific advice about teaching this topic because it very much depends on the implementation choices you made for your DTD and the types of formatting and printing applications or online viewing applications you intend to have.

Note

The word “linking” is overloaded with specific technical meanings, for example, to mean online navigation hyperlinks. But at this stage we are talking about teaching authors, often nonexperts in these specific fields, the general process of putting two things in relationship when they need to do so. The particular mechanism for making the association needs to be taught, but does not change the essential nature of the action.

Often, some linking can be done automatically by the system, and in this case authors need to facilitate the automatic linking process by marking up data-level information thoroughly. For example, if terms in the text can automatically be linked to a company-wide dictionary database that defines the terms, authors must only mark up the terms in text. But for associations that cannot be made automatically for whatever reason, authors must know when and how to make the link.

As we've suggested elsewhere, one way to organize links is into the following types:

  • Anchors that bind an element, nontextual object, or annotation to one or more particular places within the document

  • Cross-references that link to other parts of the current document or external documents, and suggest that the reader seek out the target of the link

The ease of making such links will vary according to the sophistication of your production system. In all cases, make sure the trainees understand the underlying philosophy of each linking process before they learn the mechanism with which to implement it. If they do not learn the basic concept, after a month they won't be able to remember the syntax and will be unable to find it again. If you miss this part of the training, your documents may contain few links, particularly if the basic writing methodology being used is not optimized for hypertext presentation. Your DTD most likely will not prevent this situation from happening, and if you want to build a hypertext application on top of your documents, you may find the markup too poor to support it.

Again, make sure each new conceptual input is immediately followed by a paper example where various linking processes must be applied, and check the trainees' work for proper matching of IDs and references, correct location of IDs, and so on. If you have naming conventions for IDs, graphic file names, and so on, make sure to cover them here.

13.3.2.5. Miscellaneous Topics

In this part of the training program you address all the features of the DTD or of your specific applications that may still need some explaining.

You may want to teach how to include special characters within the text by presenting the character entities the DTD makes available and how they can be referenced.

Similarly, you should cover the use of any general entities and their text string equivalents that you have defined specifically for the line of work of your authors. As using the entities imposes an additional workload on the authors, it is important they understand the rationale for using the entities. Often such entities contain volatile information that might change at any time, especially at the last minute when there is no time to update documents. A typical example would be a product name changed by the marketing department of a company during the final days of manufacturing.

Once the basic concept of presentation independence has been assimilated, you can cover how trainees should properly control the look of the output by inserting processing instructions or using style-related attributes and elements. How and when not to do these things is as important as how and when to do them.

Finally, you can present all the features you have built into your various applications that facilitate the authors' work: markup templates, generated text, and so on.

13.3.2.6. Conclusion of the Lectures and Paper Exercises

Once you have finished the initial presentations and paper exercises, provide a corrected paper copy of the documents used for all the exercises so that trainees who might have skipped over a difficulty can find their way back again when they are not in training anymore.

The trainees should have all the DTD knowledge required to be excellent “taggers.” Now they need to learn how to insert content and markup on their computers.

13.3.3. Computer Labs

The purpose of this part of the training is to ensure that not only your trainees know the DTD but that they know how to mark up document instances in the editing software and environment they will be supplied with. This implies two steps: learning the editing software and environment, and performing markup exercises at the keyboard. This latter part breaks down into three different types of exercises that gradually build the necessary skills:

  • Marking up the content of documents that have already been marked up on paper

  • Marking up the content of documents never seen before

  • Creating new content and simultaneously marking it up

13.3.3.1. Exercises on the Editing Software and Environment

No matter what the computer platform, you must first make sure that the trainees master the usual commands, instructions, and handling of the applications in this environment. This is not the place to teach people how to use Windows. You are only supposed to teach them the editing software.

First, demonstrate the basic features of the software by using a previously prepared document instance. These will need to include the obvious SGML features such as inserting elements, changing elements, and inserting attribute values, as well as cutting, copying, and pasting.

Have the trainees start on their own with the same instance, with a list of tasks to perform. If you have built in some challenging tasks, such as inserting empty elements, making links, or declaring and referencing entities, you'll have the opportunity to explain advanced features and get the trainees to use these features immediately.

When everybody is sufficiently at ease with the software, you can move on to real exercises.

13.3.3.2. Markup Exercises on Known Documents

This part of the training is based on the document you distributed for the paper exercises previously. The trainees have marked up this document on paper, and they must now apply the same markup to the content of the document, which you have made available on line. The purpose of this step is to move from a conceptual approach to a practical one. The trainees will not encounter any markup decision difficulties as such; they will just have to tame the editing software so that it does what they want.

Start by providing an electronic plain-text version of the document used for the paper exercises. Let the trainees mark it up according to what they have on paper, which should be correct since it will have been corrected at the end of the paper exercises.

When they're done, have them check the documents with a validating parser. When all problems have been resolved, print for each trainee the correct marked-up instance.

By this point, the trainees should have a feeling of achievement, because they feel confident about both using the editing software and environment and applying the appropriate markup. It is time to let them tackle both problems at once.

13.3.3.3. Markup Exercises on Unknown Documents

In this part of the training, the trainer's role is only to provide plain-text versions of documents that are interesting in terms of markup variety and difficulty, along with formatted versions. Then it is the trainees' turn to work; the trainer is only in the room for support.

At the conclusion of this part, the trainees will probably be feeling confident that they can carry out the task of writing and marking up SGML instances. This assessment of their abilities is not strictly accurate. What they have been doing is “post-tagging” existing documents with a formatted copy to help them. This is far from document creation, which is the next step.

13.3.3.4. Creation and Markup of New Documents

Only when authors are able to create new documents and deliver them with the appropriate markup can you be sure that your training has been successful and that they master the DTD and the editing software.

This part of the training is difficult to deliver because it is awkward to order trainees: “Write new text!” Even if writing is their job, they usually perform it with a set goal. As a consequence, if your audience is homogenous in competence and interest, try to define a precise subject on which they must create a new document and, in the process, plan the document's structure and mark up the instance.

This is a long and costly process. You might want to have groups of trainees share the writing task to limit the time assigned to this task, or more drastically, let trainees work on this assignment outside the training session, in order to deliver the results at the beginning of the next training phase. Making the assignment this way is the perfect liaison to the training followup.

13.3.4. Conclusion of Initial Training

Now that the initial training is over, it is useful to have everybody build a synthesis of what has been learned. The trainees should now be prepared to produce real documents, and in order to move to the next phase of training they will be required to do so. At this point you can introduce them to the support team, and you should remind them how to get help and report problems.

13.4. Phase 2: Training Followup

Compared to the initial training, the followup program is much shorter and more informal. Its goals are to control what knowledge is left from the previous training, to test that the concepts the trainees remember are accurate (it usually requires some tuning) and to help them solve problems they have encountered since the end of the training. Therefore, the followup cannot take place unless the trainees have actually been exercising at their keyboard and producing sample documents.

First, quiz the group orally to figure out what has been absorbed and correct wrong ideas. Next, gather all the problems encountered by the trainees and sort them out orally, in writing, by showing an example on the computer, or by referring to where it is explained in the user documentation. When this is done as a group , people have the feeling they are less isolated with their problems, that it is normal to have them, and that there is a way out.

The support people should have kept a list of the problems and solutions encountered and should present them here, as most trainees usually forget what their difficulties were as soon as someone has explained how to fix the problem. You can later distribute a troubleshooting list that shows all the problems and solutions; this list should be used by the DTD maintenance team to improve the system or complete the user documentation.

Next, you can inspect particularly difficult pieces of marked-up documents together and let the group express suggestions on them. In cases where there are different markup options or where the problem cannot be easily solved, people need to know a “trick” to get around the problem or a mnemonic to help them remember the solution.

Finally, once again remind trainees how to find, fill in, and send bug report and enhancement request forms.

13.5. Phase 3: Refresher Course

The conclusion of the training activities is a short refresher course or “booster shot”; it takes place about three or four weeks after the training followup and has the same goal. However, by now the trainees have much more experience and a broader perspective, and their questions and difficulties are different.

This course often shows a division in the trainee population: the people who have made the mental jump and those who have not. You may want to separate the trainees into two groups because the learning speed and the content of the course for the two groups are going to be very different.

The slow group will want to go back to the basic concepts and to the problems they have met, and will want certainties. With them, it will be necessary to go back to what they know of the document class and to the writing standards guide if there is one in the company, and generally to keep very close to the practical side of their jobs. Inspecting the markup of a piece of document is always a favorite. Reading and explaining parts of the user documentation is less appealing but very efficient too.

The people in the fast group are the potential “power users.” Typically, they have already taken the DTD and the tools to their limits and are already coming back with requests for enhancements and changes. They are avid about “tricks” and enjoy sharing how they have fixed various problems. The trainer's task here is to note what is being said and distribute it to the whole group so that everybody can share the knowledge.

At the end of the refresher course it is rewarding to gather the trainees as one group again to show how their work can be utilized. If you can show the formatted result of a document, or an online-viewable version including, for example, hyperlinks, you will give everybody a feeling of achievement, usefulness, and motivation to go on with the markup effort. A good synthesis of the course is to remind trainees about the “dos and don'ts” of markup, as listed in Section 13.3.1, “Introduction”.

13.6. Phase 4: Quality Inspection of Documents

In a number of companies and organizations where the production of documents is crucial to the activity (publishers with their books, manufacturers with their product documentation, administrations with their rules), it is common to perform a review or inspection of the content and outline of the documents, similar to the computer industry's “code reviews,” which are done on modules of programming code. The advent of the ISO 9000 Quality Assurance Certification process has encouraged these types of review.

After any document content inspections have been successfully passed, you should consider using the same process, if more informally, to gradually increase the quality of the markup in the SGML documents.

The problem is that, although the DTD is often viewed by authors as an unbearable constraint, it never obliges authors to include sophisticated and accurate markup in their documents. Often, authors try to get away with just the minimum document hierarchy, paragraphs, and lists, or they commit Tag Abuse by marking up parts of the content not for what it meant but for the look it would produce on paper. Tag Abuse is is just as dangerous as not marking up content, because when you want to make proper use of the content based on the markup, you end up producing absurdities.

To prevent both of these drawbacks, the quality inspection procedure provides an official framework where work is not assessed by quantity and time span but by quality. These inspections can be traumatic for some authors. Therefore, we recommend that it be done one-on-one, in the privacy of an office.

There are ways authors can assess the quality of their work before the inspection. One of these ways is to ensure a previous review with the support people. The second is to use software tools that provide statistics on the density of the markup in documents, which can indicate, in a crude way, the quality of the markup. Such tools are relatively easy to build. They are specific to each DTD and to what the editors in the company value in the documents to be published. For each instance, these tools could:

  • Show the depth of the hierarchical structure used and warn if it seems abnormal.

  • Print the number or the percentage of each type of element and compare them with usual percentages. This can be useful for figures, examples, index entries, and so on.

  • Figure out how much of the data-level information, particularly key data, has been marked up or just ignored.

Markup evaluation tools are not expected to run a formal inspection on documents; they are just meant to give clues about what might be wrong and prepare for the human inspection. Such tools have to be taken with a grain of salt. They are useless if you do not provide instructions on their proper use and the expected acceptable results. You can develop markup density benchmarks by running the tools on documents recognized for their high quality in writing and markup.

If the results of the human inspection happen to be poor, the author is supposed to fix his or her document according to the recommendations of the inspector, with the help of the support people. This process is iterative until the quality of the markup in the document is acceptable.

13.7. Phase 5: Information and Training on DTD Updates

This last phase is not part of the original training or post-training program. It occurs as the DTD starts being actively used and when no one thinks about training the users any longer. Still, when major updates of the DTD are made based on the reports and requests of the users, the first people who should be informed are the users themselves. Experience shows that it is mainly the DTD design team and the implementor who know about changes, and the knowledge does not go further.

We believe that if alterations are serious enough to produce a major DTD release, short training sessions of a half day should be organized for all the authors involved to:

  • Describe the changes and new markup features

  • Explain why they were done

  • Show how to use them

  • Explain and discuss how they are going to affect the authors' work

  • Explain how to handle existing documents in the light of the changes

Not only are these small training sessions cost-effective, but they are crucial for keeping the author's morale high: They feel they are still part of the process, their reports and requests have been heard and responded to, and they are immediately operational after an update.

If these additional training sessions cannot be organized, it's helpful to write and distribute release notes or a newsletter explaining all these points to authors.

13.8. Training Program Administration

This section describes how to prepare for and organize the training sessions and materials.

The sessions will need to be adapted to the population, local conditions, the complexity of the DTD, the ambition of the training, and the resources allocated to the training portion of the SGML project. Our suggestions are based on teaching complex DTDs with as many as 300 elements. We assume it is a high priority to have the trainees working productively on SGML documents as soon as possible.

13.8.1. Prerequisites

The trainees must meet these prerequisites:

  • Know the documents covered by the scope of the DTD

    This allows you to jump right into teaching the markup model for that class of documents. If the trainees do not have this basic knowledge, then you must first teach your authors how to write the documents before they can learn how to mark them up, and the first part will take much longer than the second will.

  • Know the computer systems they will be working on

    Whatever the hardware platform and the system running on it, if trainees are not familiar with it, you will need to add a computer training session, which may be quite long and complex, before the DTD training session. The more you add to the amount of new concepts and new tools to learn, the longer the learning curve will be. If the authors need training on the systems, we suggest you complete this training well beforehand and let them get used to the systems before starting the DTD training.

  • Be assigned to a job related to the training in the near future

    Ths ensures that trainees will apply the training immediately or soon thereafter. If the training is given too early, for example before hardware and software is available or before any documents are planned to be written in SGML, by the time they need the competence they will have forgotten everything about it. Also, if the training is given to people who have no direct motivation to achieve something with it, then they will feel bored rather than challenged by the course material, and will be less receptive when they really need the information. Giving people some general SGML background before knowledge is needed for a specific project is a laudable goal, but it is a different type of training entirely.

The training session has a prerequisite of its own: The computer lab environment should be identical to the environment the authors will work in to the extent possible, because otherwise there will be a heavy loss of energy when the authors have to learn a new tool on their own. This usually militates in favor of on-site training, to benefit from the equipment, the local network, and access to common databases. Doing the training off-site has the advantage of freeing the authors completely from their daily tasks, management, and unavoidable tie-ups, but it is bound to require an environment that has differences from the future system and environment.

If you can organize a training session where all these prerequisites are met, you are well on the path to success.

13.8.2. Number of Participants

Defining the number of participants for a training session is always difficult because there are conflicting interests. Managers usually favor large groups of people in training sessions because the more people you put in the same room, the less expensive the session becomes and the quicker the whole population who needs training will be trained. Trainers and trainees usually prefer small groups because the fewer people in each session, the easier it becomes to have the equipment available, to have trainees active at all times, and to have the trainer available to rectify any mistake as soon as it occurs.

As usual, the solution is probably halfway between the extremes. We have found that it is extremely effective to have two people at each computer because they discuss markup strategies, take turns in applying markup, and generally help and teach each other. Also, a group of a dozen people is lively, inventive, and representative of the most common attitudes, so discussions within the group are interesting and bring a lot to each participant. A smaller group runs the risk of being somewhat dull and also being so intimate that people feel discouraged from asking questions and expressing their worries. A much larger group is simply too big to handle; no one can get a word in edgewise, and the trainer does not have time to attend each individual problem.

A group of 12 to 16 trainees with 6 to 8 machines seems to be an efficient compromise.

13.8.3. Choice of Trainers

Choosing DTD trainers is a difficult art, because when teaching a DTD, the subject matter is so complex that the first reflex is to confide that training to the person who knows the DTD best: the implementor. This can be a fatal mistake.

The implementor is often a fully trained computer scientist who has mastered the art of programming. He or she seldom has the other competencies required to teach a DTD to authors from the field: teaching skills, writing experience, and a thorough knowledge of the daily tasks of the trainees with their associated constraints and difficulties. On the other hand, it might be difficult to teach a professional trainer the world of the document class, SGML concepts, the intricacies of the DTD, and the training program itself.

We have found it effective to have several different people from the document type design team serving as trainers for different topics. They not only know the DTD by heart, but they also know the context and history, as well as the users' most common difficulties and requests. Each person will have a domain of excellence, whether in explaining the structure and the element types, or in teaching a system or a tool, or in knowing how to conduct an inspection, or in providing support.

This separation of tasks has two immediate benefits. First, as no one explains things the same way, it gives the trainees several different opportunities to understand the contents of the training. It also adds diversity and helps break the monotony of the sessions. Second, the trainees are grateful to have been taught by people just like them, who know the trade and can understand their problems. Although this approach may not seem very orthodox, we recommend it as a way to limit the risk of producing a low-quality, ineffective training program.

13.8.4. Length and Organization of the Training

This topic of training length and organization is one of the most controversial, because the decisions you make here will determine the cost of the training, the loss of productivity of authors during the training sessions, the utilization of key resources (rooms, computers, trainers, support people, and so on), and the planning of when people will be able to deliver acceptable documents.

Unfortunately, the decisions are usually made the other way around. People in charge of training receive a budget, usually too low, and set dates to have people delivering the next batch of documents. They then start building the training with these constraints. However, the fact that this is the current way to do things does not mean it is the proper way to do them. This section contains some arguments that may help you obtain training conditions that are likely to increase the success of DTD training.

The experience of people in teaching large, complex DTDs seems to show that a minimum of ten days per trainee is needed.

Ten days does not mean two weeks of elapsed time, though. Most people have found out that such training is more efficient if it is stretched out over time. Thus, we suggest the following allocation of training time across the phases:

  • Five days for the initial training

  • One week of absorption time, then one day for the training followup

  • Three weeks of absorption time, then two days for the refresher course

  • Between one and two days of individual attention for each trainee for quality inspection of documents whenever each trainee has produced a real document

  • A half-day group session for training on DTD updates at each update

Because learning a DTD usually requires real intellectual effort, the training should be intense but not so dense that it muddles people's minds. We have experienced two ways to achieve the right density: Either train people for ten half-days in a row, or train them five days in a row but alternate at least four types of activities each day. For instance, you could start with a lecture, then do a paper markup exercise, then do an exercise involving some play with an editing tool, then do an online markup exercise. With these options, trainees have time to pause and think of questions that they will have a chance to ask the trainer later. The absorption of concepts and know-how is more gradual and effective.

Ten days per trainee will mean much more for the trainers and the support people who will be part of this training. First, the trainers will need a minimum of five days to prepare the first training session. This preparation will decrease to one day for the following sessions, if they are similar. Then they must actually deliver the initial and followup training programs. The refresher course may require four days instead of two if the trainers decide to split the group in two to provide the “slow” and the “fast” trainees what they expect. For the document inspections, which involve individual attention, figure on an average of one and a half days per trainee. Assuming a group of 12 trainees, this results in 18 days. DTD update training will require a about one more day. The total time commitment for a person who does all the training is 34 days.

If you are put off by the amount of time needed by both the trainees and the trainers, compare it with the time they needed previously to learn and relearn the use of style sheets and templates, and the effort it took to reach consensus on using them!

13.8.5. Training Materials

To carry out the training sessions, the training materials must be carefully planned and prepared. The material might take various forms, for example, slides and paper handouts. Some materials are meant for the trainer's use only, and some are also for the trainees. The moment when they should be introduced in the course varies.

Table 13.1, “Materials for a Typical DTD Training Program” outlines a scenario for the preparation and dissemination of training materials for a typical DTD training program. Of course, this table is only indicative of some possibilities.

The only document mentioned in this table which was not mentioned and described before is the training poster. Even when handwritten, when the training budget is on the low side, the training poster is efficient for beginners. The idea is to have a large piece of cardboard behind the computer, reminding the authors of the main hierarchical and IU structures. It nicely complements the sorted lists of elements which are defined but not explained in context. Not only it is useful during the training, but also during the author's first steps at the keyboard as a sort of large quick reference card.

The amount of training material listed here may seem huge, but believe it or not, it will all fit in a single binder (albeit a thick one!).

Table 13.1. Materials for a Typical DTD Training Program

Training Material When to Introduce Who Type
Presentation of the global approach Phase 1, introduction Trainer, trainees Paper, overheads
User documentation Phase 1, lecture on the DTD Trainer, trainees Paper
Tree diagrams of document hierarchy and information pool (also in user documentation) Phase 1, lecture on the DTD Trainer Overheads
Thematic list of components (IUs in one color, data-level components in another, entities, cross-references, and so on) Phase 1, lecture on the DTD Trainer, trainees Cardboard or paper
Paper exercises: document samples Phase 1, exercises on the DTD Trainer, trainees Paper, overheads
Paper exercises: manually marked-up corrected version (optional) Phase 1, after finishing exercises Trainees Paper
Computer exercises 1: electronic version of document samples Phase 1, computer lab on manually marked-up document Trainer, trainees Paper
Computer exercises 1: valid marked-up instance Phase 1, end of computer lab on manually marked-up document Trainer, trainees Electonic (plain text)
Computer exercises 1: formatted file of document (optional) Phase 1, end of computer lab on manually marked-up document Trainees Electronic
Guided tour of the editing software: instance that illustrates features Phase 1, computer lab Trainer, trainees Electronic
Computer exercises 2: base document sample Phase 1, computer lab on unknown documents Trainer, trainee Paper, electronic (plain text)
Computer exercises 2: valid instance (optional) Phase 1, computer lab on unknown documents Trainer, trainee Electronic
Reference poster to paste behind the computer (optional) Phase 1, end of computer lab Trainer, trainees Cardboard or paper
Formatted output or online document to browse (optional) Phase 3 Trainees Paper or electronic
List of problems and solutions or workarounds Phase 2 and Phase 3, at end Trainer, trainees Paper
Bug report and enhancement request forms Phase 2 Trainer, trainees Paper, electronic
Markup dos and don'ts list (optional) Phase 3, at end Trainer, trainees Paper
Reference information: articles and bibliography about SGML and its benefits (optional) End of the course Trainer, trainees Paper

13.9. The Learning Curve

The areas where there is the least available data about SGML projects are their costs and their duration. Unfortunately, these are the first two questions that managers ask when they are considering such a project. This section provides some figures related to training, based on our personal experience. They are likely to be inaccurate for other cases, but they may provide a useful starting point when planning a DTD training program for figuring out when trainees will be fully productive.

13.9.1. Time Span

As mentioned in Section 13.8.4, “Length and Organization of the Training ”, the learning period lasts about three months, assuming that a support team has been available during the whole period, and the logistics of computer systems availability and so on have been taken care of. To be more accurate, however, authors typically admit to feeling they have mastered the whole process only when their first project has been delivered and has successfully passed the quality inspection.

Authors usually make progress as follows: After the initial training, authors enter a “crawling phase” lasting a few weeks. Then, over the next few weeks, they begin to assimilate the information. Then they often have a week where they experience a “crisis of faith.” Finally, they cross the threshold of full autonomy, where they can engage in real productive work.

The date each person reaches the autonomy threshold varies with that person's learning capacity and interest.

13.9.2. Productivity Assessment

When trying to assess the loss of productivity, we interviewed technical writers who had to produce manuals about 250 pages long in about three months with a structured editor they did not know beforehand.

Their conclusion was that they had a drop in productivity of about 35 percent during a month and a half, which included the initial training and the mastering of the tool. Then this was reduced to a productivity loss of about 10 percent until the end of the first manual.

They admitted that producing the second manual was no added difficulty at all and that having to mark up their text as they created it was no overload at all. It seems that the thinking process is so important compared to the typing time that a few tags more were not significant.

Some writers even admitted that they had the tree diagrams “hardwired” in their heads and that this was helping them now to structure their thoughts to start writing more quickly.

The interviewed writers were, of course, successful writers. To minimize productivity loss, they made the following recommendations:

  • Start writing immediately during or after the initial training.

  • Make sure you knew the editing environment well in the first place, not to be bothered by problems unrelated to the structuring of the document.

  • Choose to write a document where content was in no way a difficulty (for instance, a new revision of a document you have already written).

  • Stop writing when nothing was clear in your head any longer, and start fresh after a few days.

Some tried to compare productivity by keying in the tags as they went with their structured editor with writing the contents of chapters of their manual with their favorite word processor then importing it in ASCII form in the editor to post-tag the content. Their assessment was that it was “hell,” and it amounted to a 50 percent productivity loss due to the lack of guidance in the markup. They had even had to turn off the validation checking to import the source document. They recommended to forget this solution and do proper conversion if people were to keep using their word processors.

The unsuccessful writers could not explain their difficulties, other than that they thought the model was too complex and that you had to think of too many things at a time. This result argues in favor of even more gradual introduction of complexities.

As a conclusion, contrary to the rumor, switching to SGML does not seem to hinder much writing productivity in the early days and at all in normal times.

13.10. Training Challenges

We believe that following the suggestions in this chapter will help make the use of your DTD a success. But we do not want to paint too rosy a picture: Training is the trickiest part of an SGML project because it is the only time (other than getting buy-in on the project in the first place!) when you will be dealing with some unwilling people. And teaching a DTD and its use to people who are not enthusiastic is indeed a challenge.

We'll conclude by summarizing what the main difficulties in training are, so you can keep them in mind and overcome them at each moment of the training.

  • Helping Authors Make the Effort

    The authors will need to agree to make the necessary intellectual effort. Whether for reasons of intellectual comfort or resistance to change, this is definitely the hardest battle to win.

  • Helping Authors Accept New Constraints

    Particularly if you have not implemented a controlled document production environment yet, it is difficult for authors to accept the permanent constraint of the model and the permanent control of the parser. This impossibility of cheating makes some writers talk about “big brother” and the “death of creativity.

  • Helping Authors Model Documents Before Writing Them

    Some authors will have difficulty accepting the need for structuring their documents before they write them, and will have trouble mastering this skill. Some people naturally write in such a way, but for others, getting there is a terribly painful path.

  • Cutting the Cord Between Content and Presentation

    The authors will need to accept their loss of power on the presentation of their documents. The WYSIWYG years and tools have given them so much freedom and so much fun in formatting their documents that pushing them to concentrate only on the intelligence of the contents and letting the formatting be the responsibility of a formatting engine is for them a sign of extreme generosity.

  • Providing Support All the Way

    Authors will need to be convinced to hold on as long as necessary until marking up information becomes second nature. As with all difficult situations, the temptation is great to just drop out so as not to be confronted with one's self-limitations. The good point of helping people to hold on, however hard it is, is the immense pleasure they feel when they finally master the use of a DTD and the editing tool.

  • Getting Buy-In on the Training Program Itself

    Last but not least is a difficulty that managers, rather than authors, face. The really hard part for a project managing is obtaining the necessary time and resources to organize a really solid training program.

If you have designed and developed a DTD using the methodology, documented it properly, delivered effective training, been vigilant in observing the difficulties encountered by the users, and helped them to overcome the difficulties, your DTD project is certain to be successful.