Advanced Technical Writing 2006 Session #3

Today in Class… ► Teams pitch poster concepts:  Meet with your editorial team, show us how your material fits with the whole concept ► Brief intro to XML ► Basics of Topic-Based Authoring

A brief introduction to XML As customized as necessary & As generalized as possible

What is XML ► eXtensible Markup Language (much cooler than eML, eh?) ► Think of it as a generic way to describe markup languages…allowing users to create their own tags which describe what is sometimes called the “semantic structure” of a document

What is XML ► Still confused? XML is a subset of SGML, the publishing industry standard for describing content so that it can be stored, referenced, distributed, and presented consistently across diverse systems

This is XML* <citation> Hart-Davidson, William Hart-Davidson, William <date>2000</date><publisher> Drybooks Inc. Drybooks Inc. <pcity>Antwerp</pcity></publisher></citation> * Well formed, but not valid XML… This could be finer grained..

What does XML do? 1 XML allows you to define the pieces of information (or objects, as we came to know them last week) that make up a document in such a way as to allow both humans and machines to recognize them and act upon them

What does XML do? 2 For machines, XML defines the logical structure of the document, giving names to things so they can be recognized (parsed) or referenced in conditional statements, etc …for people, it provides a way to describe what I’d rather call the rhetorical structure of the document

How does XML work? xml Dtd style rules An xml document is made valid when a Document Type Definition (or Schema) is present that describes types of elements and the relationships among elements for the document

An XML scenario, 1 Bill is transforming a set of training materials, shipped as PDF files on a CD, for publication on the web DITA This involves recreating the manual as a set of “topics”...each is stored as an XML file

An XML scenario, 1 Bill then creates an XSLT document that describes how the web-based version should look Manual Style Rules The XSLT transforms XML into HTML + CSS for display in a browser He will later create a separate XSLT for the PDF versions…

An XML scenario, cont. Bill doesn’t worry, using the new DTD, all he has to do is create a new set of style rules. Bill’s editor wants the files in a printable format…

Topic-Based Authoring with DITA: a preview Topic - the highest level semantic unit, a topic can be of any length; documents are made up of topics (one or many) Task - one subtype of topic, a “how to” Concept - another subtype of topic, a “what is” Map - a list of references to other topics and those topics’ sub-structures used to create a particular document or “view;”

A bit more about DTDs DTDs are the place where XML tag sets are defined. They are pretty powerful meta-documents that determine what the folks reading and writing XML documents of a particular type can and cannot include, search for, etc. DITA is defined in a DTD (as well as the more muscular cousin of the DTD, a Schema)

A bit more about DTDs We can consider DTD’s, or their newer and more flexible counterparts called XML Schema, as workspaces. They define conceptual and physical boundaries for content developers Their design is a critical task for the content specialist. Well wrought DTD’s & Schema can greatly impact the both user experience, the development cycle, and, hence, the business/mission.

A DITA “workspace”: roles The following slide lists roles that team members might play in a content- production situation where DITA is in use. Read more here:

Type architect - Analyzes topic types needed to accommodate content being produced, and defines new topic types if needed. Topic writer - Writes and edits topics, according to the topic-type standards established for the project by the XML architect. Information architect - Analyzes the overall structure of the content, groups it into topic collections, and defines maps that describe the relationship of topics to each other. Build developer - Processes the DITA source topics into various formats, as needed for product deliverables. Information designer - Establishes the "look and feel" of the output presentation.

Let’s Do a Little XML exercise Think about the poster we are making. Come up with some XML tags to describe the semantic structure of the poster ► Draft a list of tags that correspond to your “topic” ► Name your tags with semantic labels… that is, identify functional objects within the document

Inside the DTD… A DTD is just a list of declarations. Let’s consider three common types : 1. The first declaration names the DOCTYPE.

Inside the DTD, 2 2. Then come declarations of document ELEMENTs.

Inside the DTD, 3 3. Finally, there may be declarations for ATTRIBUTES of an ELEMENT.

This is a DTD <!DOCTYPE citation [ [ ]>

A Few More X’s… ► What is XHTML? Quite simply, it is html redescribed as an XML DTD. Or another way to say it is that XHTML is the current default web DTD.

A Few More X’s… ► What is XSL? XSL-T? The xml stylesheet specification. XSLT is a very robust spec for transforming an XML document of one type into one of another type…meaning you can do more than just “style” information for display, you can also change it into other forms.

Good references for CSS & XML

Helpful Readings ► s/storyReader$380 s/storyReader$380 s/storyReader$380 An article on eBookWeb about XML, structure, and content. If you have it handy, you can read Rockley Ch. 14 and Ch. 20.

Next Time… ► Semantic Markup 1 - DITA, a chance to see XML in use in the TC world ► Individuals: Begin authoring the digital assets for your part of the poster ► Teams: Work on the semantic structure of your topic area