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/