SGML: SGML in UWaterloo Technical Writing (Course)

SGML: SGML in UWaterloo Technical Writing (Course)


Subject: Re: PHIL:   Affording SGML

Date: Wed, 2 Oct 1996 14:57:45 GMT

From: papresco@calum.csclub.uwaterloo.ca (Paul Prescod)

Newsgroup: comp.text.sgml


------------------------------------------------------------------------

In article <01bbae54$59ecd600$72091b26@wally.austin.passage.com>,
W. Eliot Kimber <kimber@passage.com> wrote:

>When I graduated with a degree in
>technical writing in 1984 we were taught how to create good words using
>typewriters or their electronic equivalent.  That is how most tech writers
>are still taught [question: how may tech writing programs teach or use SGML
>(other than HTML, which doesn't count because HTML is just an SGML
>typewriter replacement, not an information management tool)? I think the
>number is very low].  

We have a technical writing course at the University of Waterloo that
uses SGML. Waterloo has one of the biggest technical writing programs
in Canada and most "Professional Writing" students take it.

Students submit their assignments in SGML through HTTP and we convert
them to HTML. So far, this term the [results look good]. Of course,
like any challenging or unique course, we get mixed responses from the
students. Some love it, some drop it. Many go on to help us build the next
bigger, better, iteration of the course.

Most students never step into a classroom and the only text book is the
[Web site.] The [course materials] are all on the Web and available in
[RTF and HTML for download and offline printing or browsing]. They were
all done in SGML and published in HTML. They go in much greater depth
than would a traditional text book (which may be good or bad, depending
on how you intend to use them).

Here's some info from a spiel:

The University of Waterloo English Department is using SGML to develop
hypertext courseware for a second year Technical Writing course on the
World Wide Web. Subject matter experts from the university and business
communities develop tutorials in the InContext structured word processor
and save them as SGML. Then they run them through special Windows-based
conversion software to create files in the World Wide Web hypertext
format, the HyperText Markup Language (HTML). This software was written
for English 210E and we were pleased to find that the printed and online
versions of our documents are generally of higher quality than we would
have created by hand. The automatic publishing process removes the
inconsistencies that plague manually formatted print and online documents.

SGML is also used for student assignments. All assignments are written
in SGML and submitted. The submission system converts them and mounts
them on the World Wide Web for peer review. Marked assignments with
marker's comments are returned through password-protected Web sites.

---

English 210E uses three DTDs for resume, letter and report documents. The
resume and letter are very confining DTDs intended to be an easy
introduction to SGML. Instead of overwhelming students with choices,
they give them a strict "menu" of core options. An English 210E student
is currently working to make a more expansive version of the resume DTD
for advanced students.

The report DTD is the most expansive. It has elements for all of the
common idioms of documentation, such as the footnote, the reference
and the bibliographic entry. Although these elements are derived from
elements of traditional documentation, they are even more useful on the
World Wide Web.

The report DTD also has elements for linking to multimedia and World
Wide Web resources. Authors are encouraged to use multimedia and Web
features where they can genuinely enhance meaning but to always bear
in mind the essential multiple-media nature of the document they are
creating. If an author uses movies instead of pictures then the document
may lose vital information in the translation to print. If they use
pictures instead of text, then the document may lose information when
displayed on non-graphical browsers. An ideal multiple-media document
uses a multilayered approach that allows a wide and diverse audience.

All three DTDs have a "marker's comment" element. This element removes
the need for markers to write "around the edges" and between the lines
of a print document. The marker's comment is extracted from the document
and put into its own file, like a footnote. A colorful icon is inserted
into the document in its place to serve as a visual identifier and link
to a marker's comment. An assignment with many marker's comments per
paragraph is highly analogous to a print essay with red scribblings all
over. From within the marker's comment, the marker can "link back" to
any other part of the document or to any World Wide Web resource.

Currently, a marker's comment or footnote replaces the document in
the reader's browser. This is due to limitations of current browser
technology. The last wave of Web browsers could only display one document
or document fragment at a time. When browsers integrate support for the
HTML 3.0 footnote element, or the Netscape frame element, the converter
can be updated to uses these facilities. Documents that are already
encoded in SGML will automatically benefit from this change. No change
to the document's SGML file will be necessary.

Editing

The SGML word processor used in English 210E is InContext 2 from InContext
Systems. InContext 2 is a Windows based structured word processor that
can be used to create and edit SGML files. InContext Systems generously
donated the product for the use of English 210E.

Even in this graphical environment, our authors consider structured
editing to be quite different from the "WYSIWYG" (What You See Is What
You Get) format-oriented word processing of a traditional word processor
like Microsoft Word or WordPerfect. In traditional word processors,
an author's primary responsibility is to make their work look good on
a piece of paper. The word processor offers obvious, visual tools for
manipulating the formatting and layout of the document. In a structured
word processor, the author has the higher responsibility of making sure
that all of the components of the document are accurately labeled or
"tagged."

If an author uses the "tab" key to simulate indentation and create a
numbered list, the SGML conversion software cannot accurately generate
the list numbering according to the consistent style specified in the
style sheet. If they encode a title using an emphasis tag instead of a
title tag, then that title will not appear in the table of contents. The
structured editing software can help in this process, but it cannot make
it foolproof. Though this SGML development process is very different
from traditional word processing, it is well within the ability of most
people who are familiar with word processors. In addition, the state
of the art in structured word processing tools is rapidly improving
just as the first format-oriented word processors did in their early
days. Vigorous competition in this market is generating cheaper, more
capable products every day.

All of the English 210E students and content providers use SGML for their
assignments and tutorials. Furthermore, once authors get over the SGML
learning curve, the SGML process frees them from many formatting and
referencing processes that would have taken time in a traditional document.

 Paul Prescod

References:

 assignment [results look good]
 http://itrc.uwaterloo.ca/~engl210e/BulletinBoard/ViewStudentAssignments/

 [course materials] on the Web
 http://itrc.uwaterloo.ca/~engl210e/BookShelf/

 [RTF and HTML for download and offline printing or browsing]
 http://itrc.uwaterloo.ca/~engl210e/BookShelf/Introduction/CourseSoftware/

 [Web site]
 http://itrc.uwaterloo.ca/~engl210e/